amazon-alexa

## Overview

Complete integration with Amazon Alexa to build intelligent voice skills, turn Alexa into an assistant with Claude as the brain (the Auri project), and integrate with the AWS ecosystem (Lambda, DynamoDB, Polly, Transcribe, Lex, Smart Home).

## When to Use This Skill

- When you need specialized assistance with this domain

## Do Not Use This Skill When

- The task is unrelated to amazon alexa
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

> You are the expert in Alexa and AWS Voice. Mission: turn
> any Alexa device into an ultra-intelligent assistant using
> Claude as the LLM backend, with neural voice, persistent memory, and
> Smart Home control. Key project: AURI.

---

## 1. Ecosystem Overview

```
[Alexa Device] → [Alexa Cloud] → [AWS Lambda] → [Claude API]
    Speech        Transcription    Logic          Intelligence
      ↑               ↑               ↑                ↑
    User          Intent          Handler          Anthropic
                               + DynamoDB
                               + Polly TTS
                               + APL Visual
```

## Components Of The Auri Architecture

| Component | AWS Service | Function |
|-----------|-------------|--------|
| Speech → Text | Native Alexa ASR | Speech recognition |
| NLU | ASK Interaction Model + Lex V2 | Extract intent and slots |
| Backend | AWS Lambda (Python/Node.js) | Logic and orchestration |
| LLM | Claude API (Anthropic) | Intelligence and responses |
| Persistence | Amazon DynamoDB | History and preferences |
| Text → Speech | Amazon Polly (neural) | Auri's natural speech |
| Visual Interface | APL (Alexa Presentation Language) | Screens on Echo Show |
| Smart Home | Alexa Smart Home API | Device control |
| Automation | Alexa Routines API | Intelligent routines |

---

## 2.1 Prerequisites

```bash

## Ask Cli

npm install -g ask-cli
ask configure

## Aws Cli

pip install awscli
aws configure
```

## Create A Skill From A Template

ask new \
  --template hello-world \
  --skill-name auri \
  --language pt-BR

## └── .Ask/Ask-Resources.Json

```

## 2.3 Configure The Invocation Name

In the `models/pt-BR.json` file:
```json
{
  "interactionModel": {
    "languageModel": {
      "invocationName": "auri"
    }
  }
}
```

---

## 3.1 Essential Intents For Auri

```json
{
  "interactionModel": {
    "languageModel": {
      "invocationName": "auri",
      "intents": [
        {"name": "AMAZON.HelpIntent"},
        {"name": "AMAZON.StopIntent"},
        {"name": "AMAZON.CancelIntent"},
        {"name": "AMAZON.FallbackIntent"},
        {
          "name": "ChatIntent",
          "slots": [{"name": "query", "type": "AMAZON.SearchQuery"}],
          "samples": [
            "{query}",
            "me ajuda com {query}",
            "quero saber sobre {query}",
            "o que voce sabe sobre {query}",
            "explique {query}",
            "pesquise {query}"
          ]
        },
        {
          "name": "SmartHomeIntent",
          "slots": [
            {"name": "device", "type": "AMAZON.Room"},
            {"name": "action", "type": "ActionType"}
          ],
          "samples": [
            "{action} a {device}",
            "controla {device}",
            "acende {device}",
            "apaga {device}"
          ]
        },
        {
          "name": "RoutineIntent",
          "slots": [{"name": "routine", "type": "RoutineType"}],
          "samples": [
            "ativa rotina {routine}",
            "executa {routine}",
            "modo {routine}"
          ]
        }
      ],
      "types": [
        {
          "name": "ActionType",
          "values": [
            {"name": {"value": "liga", "synonyms": ["acende", "ativa", "liga"]}},
            {"name": {"value": "desliga", "synonyms": ["apaga", "desativa", "desliga"]}}
          ]
        },
        {
          "name": "RoutineType",
          "values": [
            {"name": {"value": "bom dia", "synonyms": ["acordar", "manhã"]}},
            {"name": {"value": "boa noite", "synonyms": ["dormir", "descansar"]}},
            {"name": {"value": "trabalho", "synonyms": ["trabalhar", "foco"]}},
            {"name": {"value": "sair", "synonyms": ["saindo", "goodbye"]}}
          ]
        }
      ]
    }
  }
}
```

---

## 4.1 Main Python Handler

```python
import os
import time
import anthropic
import boto3
from ask_sdk_core.skill_builder import SkillBuilder
from ask_sdk_core.handler_input import HandlerInput
from ask_sdk_core.utils import is_intent_name, is_request_type
from ask_sdk_model import Response
from ask_sdk_dynamodb_persistence_adapter import DynamoDbPersistenceAdapter

## ============================================================

@sb.request_handler(can_handle_func=is_request_type("LaunchRequest"))
def launch_handler(handler_input: HandlerInput) -> Response:
    attrs = handler_input.attributes_manager.persistent_attributes
    name = attrs.get("name", "")
    greeting = f"Oi{', ' + name if name else ''}! Eu sou a Auri. Como posso ajudar?"
    return (handler_input.response_builder
            .speak(greeting).ask("Em que posso ajudar?").response)


@sb.request_handler(can_handle_func=is_intent_name("ChatIntent"))
def chat_handler(handler_input: HandlerInput) -> Response:
    try:
        # Get query
        slots = handler_input.request_envelope.request.intent.slots
        query = slots["query"].value if slots.get("query") else None
        if not query:
            return (handler_input.response_builder
                    .speak("Pode repetir? Nao entendi bem.").ask("Pode repetir?").response)

        # Load history
        attrs = handler_input.attributes_manager.persistent_attributes
        history = attrs.get("history", [])

        # Build messages for Claude
        messages = history[-MAX_HISTORY:]
        messages.append({"role": "user", "content": query})

        # Call Claude
        client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
        response = client.messages.create(
            model=CLAUDE_MODEL,
            max_tokens=512,
            system=AURI_SYSTEM_PROMPT,
            messages=messages
        )
        reply = response.content[0].text

        # Truncate so as not to exceed the timeout
        if len(reply) > MAX_RESPONSE_CHARS:
            reply = reply[:MAX_RESPONSE_CHARS] + "... Quer que eu continue?"

        # Save history
        history.append({"role": "user", "content": query})
        history.append({"role": "assistant", "content": reply})
        attrs["history"] = history[-50:]  # Keep the last 50
        handler_input.attributes_manager.persistent_attributes = attrs
        handler_input.attributes_manager.save_persist

## 4.2 Lambda Environment Variables

```
ANTHROPIC_API_KEY=sk-...  (store in Secrets Manager)
DYNAMODB_TABLE=auri-users
AWS_REGION=us-east-1
```

## 4.3 Requirements.Txt

```
ask-sdk-core>=1.19.0
ask-sdk-dynamodb-persistence-adapter>=1.19.0
anthropic>=0.40.0
boto3>=1.34.0
```

---

## 5.1 Create The Table

```bash
aws dynamodb create-table \
  --table-name auri-users \
  --attribute-definitions AttributeName=userId,AttributeType=S \
  --key-schema AttributeName=userId,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST \
  --region us-east-1
```

## 5.2 User Schema

```json
{
  "userId": "amzn1.ask.account.XXXXX",
  "name": "Joao",
  "history": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "preferences": {
    "language": "pt-BR",
    "voice": "Vitoria",
    "personality": "assistente profissional"
  },
  "smartHome": {
    "devices": {},
    "routines": {}
  },
  "updatedAt": 1740960000,
  "ttl": 1748736000
}
```

## 5.3 Automatic Ttl (Expire Old Data)

```python
import time

## Add A 180-Day Ttl When Saving

attrs["ttl"] = int(time.time()) + (180 * 24 * 3600)
```

---

## 6.1 Available Voices (Portuguese)

| Voice | Language | Type | Recommended |
|-------|--------|------|-------------|
| `Vitoria` | pt-BR | Neural | ✅ Auri PT-BR |
| `Camila` | pt-BR | Neural | Alternative |
| `Ricardo` | pt-BR | Standard | Male |
| `Ines` | pt-PT | Neural | Portugal |

## 6.2 Integrate Polly Into The Response

```python
import boto3
import base64

def synthesize_polly(text: str, voice_id: str = "Vitoria") -> str:
    """Returns a Polly audio URL to use in Alexa."""
    client = boto3.client("polly", region_name="us-east-1")
    response = client.synthesize_speech(
        Text=text,
        OutputFormat="mp3",
        VoiceId=voice_id,
        Engine="neural"
    )
    # Save to S3 and return the URL
    # (needed to use custom audio in Alexa)
    return upload_to_s3(response["AudioStream"].read())

def speak_with_polly(handler_input, text, voice_id="Vitoria"):
    """Return a response using a custom Polly voice via SSML."""
    audio_url = synthesize_polly(text, voice_id)
    ssml = f'<speak><audio src="{audio_url}"/></speak>'
    return handler_input.response_builder.speak(ssml)
```

## 6.3 Ssml For Voice Control

```xml
<speak>
  <prosody rate="90%" pitch="+5%">
    Oi! Eu sou a Auri.
  </prosody>
  <break time="0.5s"/>
  <emphasis level="moderate">Como posso ajudar?</emphasis>
</speak>
```

---

## 7.1 Chat Template

```json
{
  "type": "APL",
  "version": "2023.3",
  "theme": "dark",
  "mainTemplate": {
    "parameters": ["payload"],
    "items": [{
      "type": "Container",
      "width": "100%",
      "height": "100%",
      "backgroundColor": "#1a1a2e",
      "items": [
        {
          "type": "Text",
          "text": "AURI",
          "fontSize": "32px",
          "color": "#e94560",
          "textAlign": "center",
          "paddingTop": "20px"
        },
        {
          "type": "Text",
          "text": "${payload.lastResponse}",
          "fontSize": "24px",
          "color": "#ffffff",
          "padding": "20px",
          "maxLines": 8,
          "grow": 1
        },
        {
          "type": "Text",
          "text": "Diga algo para continuar...",
          "fontSize": "18px",
          "color": "#888888",
          "textAlign": "center",
          "paddingBottom": "20px"
        }
      ]
    }]
  }
}
```

## 7.2 Add Apl To The Response

```python
@sb.request_handler(can_handle_func=is_intent_name("ChatIntent"))
def chat_with_apl(handler_input: HandlerInput) -> Response:
    # ... get the reply from Claude ...

    # Check whether the device supports APL
    supported = handler_input.request_envelope.context.system.device.supported_interfaces
    has_apl = getattr(supported, "alexa_presentation_apl", None) is not None

    if has_apl:
        apl_directive = {
            "type": "Alexa.Presentation.APL.RenderDocument",
            "token": "auri-chat",
            "document": CHAT_APL_DOCUMENT,
            "datasources": {"payload": {"lastResponse": reply}}
        }
        handler_input.response_builder.add_directive(apl_directive)

    return handler_input.response_builder.speak(reply).ask("Mais alguma coisa?").response
```

---

## 8.1 Enable The Smart Home Skill

In `skill.json`, add:
```json
{
  "apis": {
    "smartHome": {
      "endpoint": {
        "uri": "arn:aws:lambda:us-east-1:123456789:function:auri-smart-home"
      }
    }
  }
}
```

## 8.2 Smart Home Handler

```python
def handle_smart_home_directive(event, context):
    namespace = event["directive"]["header"]["namespace"]
    name = event["directive"]["header"]["name"]
    endpoint_id = event["directive"]["endpoint"]["endpointId"]

    if namespace == "Alexa.PowerController":
        state = "ON" if name == "TurnOn" else "OFF"
        # Call your smart home API
        control_device(endpoint_id, {"power": state})
        return build_smart_home_response(endpoint_id, "powerState", state)

    elif namespace == "Alexa.BrightnessController":
        brightness = event["directive"]["payload"]["brightness"]
        control_device(endpoint_id, {"brightness": brightness})
        return build_smart_home_response(endpoint_id, "brightness", brightness)
```

## 8.3 Device Discovery

```python
def handle_discovery(event, context):
    return {
        "event": {
            "header": {
                "namespace": "Alexa.Discovery",
                "name": "Discover.Response",
                "payloadVersion": "3"
            },
            "payload": {
                "endpoints": [
                    {
                        "endpointId": "light-sala-001",
                        "friendlyName": "Luz da Sala",
                        "displayCategories": ["LIGHT"],
                        "capabilities": [
                            {
                                "type": "AlexaInterface",
                                "interface": "Alexa.PowerController",
                                "version": "3"
                            },
                            {
                                "type": "AlexaInterface",
                                "interface": "Alexa.BrightnessController",
                                "version": "3"
                            }
                        ]
                    }
                ]
            }
        }
    }
```

---

## Full Deploy (Skill + Lambda)

cd auri/
ask deploy

## Check Status

ask status

## Test In The Simulator

ask dialog --locale pt-BR

## Specific Intent Test

ask simulate \
  --text "abrir auri" \
  --locale pt-BR \
  --skill-id amzn1.ask.skill.YOUR-SKILL-ID
```

## Create The Lambda Manually

aws lambda create-function \
  --function-name auri-skill \
  --runtime python3.11 \
  --role arn:aws:iam::ACCOUNT:role/auri-lambda-role \
  --handler lambda_function.handler \
  --timeout 8 \
  --memory-size 512 \
  --zip-file fileb://function.zip

## Add The Alexa Trigger

aws lambda add-permission \
  --function-name auri-skill \
  --statement-id alexa-skill-trigger \
  --action lambda:InvokeFunction \
  --principal alexa-appkit.amazon.com \
  --event-source-token amzn1.ask.skill.YOUR-SKILL-ID
```

## Use Secrets Manager

aws secretsmanager create-secret \
  --name auri/anthropic-key \
  --secret-string '{"ANTHROPIC_API_KEY": "sk-..."}'

## Lambda Accesses It Via The Sdk:

import boto3, json
def get_secret(secret_name):
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response['SecretString'])
```

---

## Phase 1 — Setup (Day 1)

```
[ ] Amazon Developer account created
[ ] AWS account configured (free tier)
[ ] ASK CLI installed and configured
[ ] IAM Role created with permissions: Lambda, DynamoDB, Polly, Logs
[ ] Anthropic API key stored in Secrets Manager
```

## Phase 2 — Base Skill (Day 2-3)

```
[ ] ask new --template hello-world --skill-name auri
[ ] Interaction model defined (pt-BR.json)
[ ] LaunchRequest handler working
[ ] ChatIntent handler with Claude integrated
[ ] ask deploy working
[ ] Basic test in the ASK simulator
```

## Phase 3 — Persistence (Day 4)

```
[ ] DynamoDB table created
[ ] History persistence working
[ ] TTL configured
[ ] User preferences saved
```

## Phase 4 — Polly + Apl (Day 5-6)

```
[ ] Polly integrated with the Vitoria voice (neural)
[ ] APL chat template created
[ ] APL rendering in the Echo Show simulator
```

## Phase 5 — Smart Home (Optional)

```
[ ] Smart Home skill enabled
[ ] Device discovery working
[ ] PowerController implemented
[ ] Tested with a real device
```

## Phase 6 — Publishing

```
[ ] Full test of all features
[ ] Performance OK (< 8s timeout)
[ ] Amazon certification submitted
[ ] Published to the Alexa Skills Store
```

---

## 11. Quick Commands

| Action | Command |
|------|---------|
| Create skill | `ask new --template hello-world` |
| Deploy | `ask deploy` |
| Simulate | `ask simulate --text "abre a auri"` |
| Interactive dialog | `ask dialog --locale pt-BR` |
| View logs | `ask smapi get-skill-simulation` |
| Validate model | `ask validate --locales pt-BR` |
| Export skill | `ask smapi export-package --skill-id ID` |
| List skills | `ask list skills` |

---

## 12. References

- Complete Python boilerplate: `assets/boilerplate/lambda_function.py`
- PT-BR interaction model: `assets/interaction-models/pt-BR.json`
- APL chat template: `assets/apl-templates/chat-interface.json`
- Smart Home examples: `references/smart-home-api.md`
- ASK SDK Python docs: https://github.com/alexa/alexa-skills-kit-sdk-for-python
- Claude + Alexa guide: https://www.anthropic.com/news/claude-and-alexa-plus

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis
```