# Chatbot de IA em Streaming

> Um exemplo mínimo que demonstra streaming de IA em tempo real e gestão do estado da conversa utilizando o framework Motia.

- Fonte: https://doutorai.pt/apps/streaming-ai-chatbot
- Categoria: Conversar com os teus Dados
- Dificuldade: Fácil
- Modelos: OpenAI
- Frameworks: -
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: AZURE_OPENAI_API_KEY, OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# Streaming AI Chatbot

Um exemplo mínimo que demonstra **streaming de IA em tempo real** e **gestão do estado da conversa** utilizando o framework Motia.
![streaming-ai-chatbot](/assets/apps-img/d4fa3fba4e5a12e9.webp)

## 🚀 Funcionalidades

- **Streaming de IA em Tempo Real**: Geração de respostas token a token utilizando a API de streaming da OpenAI
- **Gestão de Estado em Tempo Real**: Atualizações do estado da conversa em tempo real com histórico de mensagens
- **Arquitetura Baseada em Eventos**: Fluxo limpo de API → Evento → Resposta de Streaming
- **Complexidade Mínima**: Máximo impacto com apenas 3 ficheiros principais

## 📁 Arquitetura

```
streaming-ai-chatbot/
├── steps/
│   ├── conversation.stream.ts    # Real-time conversation state
│   ├── chat-api.step.ts         # Simple chat API endpoint  
│   └── ai-response.step.ts      # Streaming AI response handler
├── package.json                 # Dependencies
├── .env.example                 # Configuration template
└── README.md                    # This file
```

## 🛠️ Configuração

### Instalação e Configuração

```bash
# Clone the repository
git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd advanced_llm_apps/chat_with_X_tutorials/chat_with_llms

# Install dependencies
npm install

# Start the development server
npm run dev
```

### Configura a API do OpenAI

Para configurar a API do OpenAI, segue os passos abaixo:

1. **Cria uma conta**: Visita o site do OpenAI e cria uma conta se ainda não tiveres uma.
2. **Obtém a chave da API**: Após criares a conta, navega até à secção da API e gera uma nova chave da API.
3. **Instala a biblioteca**: Se ainda não o fizeste, instala a biblioteca necessária utilizando o seguinte comando:

    ```bash
    pip install openai
    ```

4. **Configura a variável de ambiente**: Define a variável de ambiente `OPENAI_API_KEY` com a chave da API que obtiveste. No terminal, executa:

    ```bash
    export OPENAI_API_KEY='sua-chave-da-api'
    ```

5. **Faz uma chamada à API**: Agora que tudo está configurado, podes fazer uma chamada à API. Aqui está um exemplo de código em Python:

    ```python
    import openai

    openai.api_key = os.getenv("OPENAI_API_KEY")

    response = openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": "Olá, como estás?"}
        ]
    )

    print(response.choices[0].message['content'])
    ```

Seguindo estes passos, estarás pronto para utilizar a API do OpenAI nas tuas aplicações.

```bash
   cp .env.example .env
   # Edit .env and add your OpenAI API key
   ```

**Open Motia Workbench**:  
Navega até `http://localhost:3000` para interagir com o chatbot

## 🔧 Utilização

### Enviar uma Mensagem de Chat

**POST** `/chat`

```json
{
  "message": "Hello, how are you?",
  "conversationId": "optional-conversation-id"  // Optional: If not provided, a new conversation will be created
}
```

```markdown
# Guia de Instalação do Projeto

## Pré-requisitos

Antes de começares, assegura-te de que tens os seguintes pré-requisitos instalados:

- [Node.js](https://nodejs.org/) (versão 14 ou superior)
- npm (geralmente instalado com o Node.js)

## Instalação

1. Clona o repositório:

   ```bash
   git clone https://github.com/usuario/projeto.git
   ```

2. Navega até à pasta do projeto:

   ```bash
   cd projeto
   ```

3. Instala as dependências:

   ```bash
   npm install
   ```

## Execução

Para executar o projeto, utiliza o seguinte comando:

```bash
npm start
```

O projeto estará disponível em `http://localhost:3000`.

## Testes

Para executar os testes, utiliza o seguinte comando:

```bash
npm test
```

## Contribuição

Se desejas contribuir para este projeto, segue os passos abaixo:

1. Cria um fork do repositório.
2. Cria uma nova branch:

   ```bash
   git checkout -b minha-nova-feature
   ```

3. Faz as tuas alterações e commit:

   ```bash
   git commit -m "Adiciona nova feature"
   ```

4. Faz push para a branch:

   ```bash
   git push origin minha-nova-feature
   ```

5. Abre um Pull Request.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro [LICENSE](LICENSE) para mais informações.
```

```json
{
  "conversationId": "uuid-v4",
  "message": "Message received, AI is responding...",
  "status": "streaming"
}
```

## 🎯 Conceitos Chave Demonstrados

### 1. **Integração com API de Streaming**

```typescript
const stream = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [...],
  stream: true, // Enable streaming
})

for await (const chunk of stream) {
  // Update state with each token
  await streams.conversation.set(conversationId, messageId, {
    message: fullResponse,
    status: 'streaming',
    // ...
  })
}
```

### 2. **Gestão de Estado em Tempo Real**

```typescript
export const config: StateStreamConfig = {
  name: 'conversation',
  schema: z.object({
    message: z.string(),
    from: z.enum(['user', 'assistant']),
    status: z.enum(['created', 'streaming', 'completed']),
    timestamp: z.string(),
  }),
  baseConfig: { storageType: 'state' },
}
```

### 3. **Fluxo baseado em eventos**

```typescript
// API emits event
await emit({
  topic: 'chat-message',
  data: { message, conversationId, assistantMessageId },
})

// Event handler subscribes and processes
export const config: EventConfig = {
  subscribes: ['chat-message'],
  // ...
}
```

## 🌟 Porque Este Exemplo É Importante

Este exemplo demonstra o poder do Motia em apenas **3 ficheiros**:

- **Streaming sem esforço**: Respostas de IA em tempo real com atualizações de estado automáticas
- **Eventos seguros em tipo**: Segurança de tipo de ponta a ponta desde a API até aos manipuladores de eventos
- **Gestão de estado integrada**: Não são necessárias bibliotecas de estado externas
- **Arquitetura escalável**: Design orientado a eventos que cresce com as tuas necessidades

Perfeito para demonstrar como o Motia torna aplicações complexas em tempo real simples e mantidas.

## 🔑 Variáveis de Ambiente

- `OPENAI_API_KEY`: A tua chave de API da OpenAI (obrigatória)

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/streaming-ai-chatbot