Spaces:
Runtime error
Runtime error
eriquesouza commited on
Commit ·
eba72b3
1
Parent(s): 5f56020
Revise agent and documentation for ISP customer service PoC
Browse files- Updated `agent.py` to reflect the new role as a customer service assistant for an ISP, focusing on resolving customer issues using past conversations.
- Modified response format to require replies in Brazilian Portuguese and emphasized empathy in interactions.
- Enhanced `README.md` to describe the new use case and structure, including details on memory types relevant to customer service.
- Adjusted `index.html` to change the chat interface label and initial message to align with the ISP context, improving user guidance.
- README.md +17 -12
- agent.py +25 -15
- static/index.html +6 -4
README.md
CHANGED
|
@@ -1,17 +1,18 @@
|
|
| 1 |
# Agent Memory — Fase 1 (Baseline)
|
| 2 |
|
| 3 |
-
|
| 4 |
-
|
|
|
|
| 5 |
|
| 6 |
## Estrutura
|
| 7 |
|
| 8 |
```
|
| 9 |
agent_memory/
|
| 10 |
├── main.py # FastAPI app
|
| 11 |
-
├── agent.py # Lógica do agente +
|
| 12 |
├── memory_store.py # ChromaDB + decay heurístico
|
| 13 |
├── models.py # Pydantic models
|
| 14 |
-
├── seeds.py # Memórias
|
| 15 |
├── requirements.txt
|
| 16 |
├── .env.example
|
| 17 |
└── static/
|
|
@@ -40,7 +41,7 @@ pip install -r requirements.txt
|
|
| 40 |
|
| 41 |
```bash
|
| 42 |
cp .env.example .env
|
| 43 |
-
# editar .env com sua
|
| 44 |
```
|
| 45 |
|
| 46 |
### 4. Rodar
|
|
@@ -51,20 +52,24 @@ python main.py
|
|
| 51 |
|
| 52 |
Abrir: http://localhost:8000
|
| 53 |
|
|
|
|
|
|
|
| 54 |
---
|
| 55 |
|
| 56 |
## Tipos de memória
|
| 57 |
|
| 58 |
-
| Tipo
|
| 59 |
-
|-------------|---------|-----------|----------------------------------|
|
| 60 |
-
| episódica
|
| 61 |
-
| semântica
|
| 62 |
-
| estado
|
| 63 |
-
| procedimental| verde
|
|
|
|
|
|
|
| 64 |
|
| 65 |
## Features da UI
|
| 66 |
|
| 67 |
-
- **Chat** com o agente em português
|
| 68 |
- **Armazém** mostra todas as memórias como cards com barra de relevância
|
| 69 |
- Cards **piscam** (dourado) quando a memória foi usada na última resposta
|
| 70 |
- Cards **novos** entram com animação verde
|
|
|
|
| 1 |
# Agent Memory — Fase 1 (Baseline)
|
| 2 |
|
| 3 |
+
PoC de **memória observável**: chat à esquerda, armazém de memórias à direita.
|
| 4 |
+
|
| 5 |
+
**Use case:** bot de atendimento de provedor de internet/TV/telefonia que armazena **falas de clientes** (como foram ditas) para extrair aprendizados bons ou ruins e ajudar em conversas futuras — sem CRM, RAG ou integrações externas.
|
| 6 |
|
| 7 |
## Estrutura
|
| 8 |
|
| 9 |
```
|
| 10 |
agent_memory/
|
| 11 |
├── main.py # FastAPI app
|
| 12 |
+
├── agent.py # Lógica do agente + OpenRouter API
|
| 13 |
├── memory_store.py # ChromaDB + decay heurístico
|
| 14 |
├── models.py # Pydantic models
|
| 15 |
+
├── seeds.py # Memórias seed (falas de clientes fictícios)
|
| 16 |
├── requirements.txt
|
| 17 |
├── .env.example
|
| 18 |
└── static/
|
|
|
|
| 41 |
|
| 42 |
```bash
|
| 43 |
cp .env.example .env
|
| 44 |
+
# editar .env com sua OPENROUTER_API_KEY e OPENROUTER_MODEL
|
| 45 |
```
|
| 46 |
|
| 47 |
### 4. Rodar
|
|
|
|
| 52 |
|
| 53 |
Abrir: http://localhost:8000
|
| 54 |
|
| 55 |
+
> Se o armazém já foi populado com seeds de outro domínio, use o botão **RESET** na UI (ou `POST /api/memories/reset`) para recarregar os seeds de atendimento ISP.
|
| 56 |
+
|
| 57 |
---
|
| 58 |
|
| 59 |
## Tipos de memória
|
| 60 |
|
| 61 |
+
| Tipo | Cor | Decay/dia | Uso (neste use case) |
|
| 62 |
+
|--------------|---------|-----------|-----------------------------------------------------------|
|
| 63 |
+
| episódica | azul | 0.03 | Situação específica que um cliente relatou |
|
| 64 |
+
| semântica | roxo | 0.005 | Padrão recorrente inferido de várias falas |
|
| 65 |
+
| estado | laranja | 0.15 | Algo que clientes disseram sobre condição atual (volátil) |
|
| 66 |
+
| procedimental| verde | 0.002 | Lição sobre o que ajudou ou irritou no atendimento |
|
| 67 |
+
|
| 68 |
+
As memórias seed em `seeds.py` incluem de propósito relatos **bons, ruins, contraditórios e desatualizados** para exercitar o armazém observável.
|
| 69 |
|
| 70 |
## Features da UI
|
| 71 |
|
| 72 |
+
- **Chat** com o agente em português (atendimento ISP)
|
| 73 |
- **Armazém** mostra todas as memórias como cards com barra de relevância
|
| 74 |
- Cards **piscam** (dourado) quando a memória foi usada na última resposta
|
| 75 |
- Cards **novos** entram com animação verde
|
agent.py
CHANGED
|
@@ -11,10 +11,13 @@ from memory_store import MemoryStore
|
|
| 11 |
load_dotenv()
|
| 12 |
|
| 13 |
SYSTEM_PROMPT = """\
|
| 14 |
-
You are
|
| 15 |
-
|
|
|
|
| 16 |
|
| 17 |
-
|
|
|
|
|
|
|
| 18 |
|
| 19 |
{memory_context}
|
| 20 |
|
|
@@ -22,11 +25,11 @@ You have access to the following memories from past experience and learning:
|
|
| 22 |
RESPONSE FORMAT — you MUST return valid JSON only, no other text:
|
| 23 |
|
| 24 |
{{
|
| 25 |
-
"response": "Your
|
| 26 |
"memories_used": ["id1", "id2"],
|
| 27 |
"new_memories": [
|
| 28 |
{{
|
| 29 |
-
"content": "
|
| 30 |
"type": "episodic|semantic|state|procedural",
|
| 31 |
"context_tags": ["tag1", "tag2"],
|
| 32 |
"summary": "5-10 word summary for display"
|
|
@@ -35,19 +38,26 @@ RESPONSE FORMAT — you MUST return valid JSON only, no other text:
|
|
| 35 |
}}
|
| 36 |
|
| 37 |
─────────────────────────────────────────────
|
| 38 |
-
MEMORY TYPES:
|
| 39 |
-
- episodic → specific
|
| 40 |
-
- semantic →
|
| 41 |
-
- state →
|
| 42 |
-
- procedural →
|
| 43 |
|
| 44 |
─────────────────────────────────────────────
|
| 45 |
GUIDELINES:
|
| 46 |
-
-
|
| 47 |
-
-
|
| 48 |
-
-
|
| 49 |
-
-
|
| 50 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 51 |
- Respond ONLY with the JSON object — no preamble, no markdown fences
|
| 52 |
"""
|
| 53 |
|
|
|
|
| 11 |
load_dotenv()
|
| 12 |
|
| 13 |
SYSTEM_PROMPT = """\
|
| 14 |
+
You are a customer service assistant for an internet, TV, and telephony provider in Brazil.
|
| 15 |
+
This is a memory-observability PoC: you help the current customer resolve their situation using \
|
| 16 |
+
what past customers said in previous conversations — stored as memories below.
|
| 17 |
|
| 18 |
+
Memories are the customers' own words (or faithful paraphrase), NOT official policy, CRM data, \
|
| 19 |
+
or verified operational facts. Use them to empathize, recognize patterns, and suggest helpful \
|
| 20 |
+
approaches that worked before — with caution when memories conflict or may be outdated.
|
| 21 |
|
| 22 |
{memory_context}
|
| 23 |
|
|
|
|
| 25 |
RESPONSE FORMAT — you MUST return valid JSON only, no other text:
|
| 26 |
|
| 27 |
{{
|
| 28 |
+
"response": "Your reply to the customer in Brazilian Portuguese (clear, empathetic, actionable)",
|
| 29 |
"memories_used": ["id1", "id2"],
|
| 30 |
"new_memories": [
|
| 31 |
{{
|
| 32 |
+
"content": "What the current customer said, preserved in their voice as closely as possible",
|
| 33 |
"type": "episodic|semantic|state|procedural",
|
| 34 |
"context_tags": ["tag1", "tag2"],
|
| 35 |
"summary": "5-10 word summary for display"
|
|
|
|
| 38 |
}}
|
| 39 |
|
| 40 |
─────────────────────────────────────────────
|
| 41 |
+
MEMORY TYPES (content is usually a past customer's statement):
|
| 42 |
+
- episodic → specific situation a customer reported ("my portability has been stuck for 5 days")
|
| 43 |
+
- semantic → recurring pattern from multiple customers ("new installs often question real speed")
|
| 44 |
+
- state → recent claim about current conditions ("the app won't load my boleto since yesterday")
|
| 45 |
+
- procedural → lesson from how support went ("asking cable vs Wi-Fi before sending a tech helped")
|
| 46 |
|
| 47 |
─────────────────────────────────────────────
|
| 48 |
GUIDELINES:
|
| 49 |
+
- Always respond to the customer in Brazilian Portuguese; be empathetic and avoid unexplained jargon
|
| 50 |
+
- Use only memories genuinely relevant to the current message
|
| 51 |
+
- List only the IDs of memories you actually drew on in your response
|
| 52 |
+
- When memories contradict each other, do NOT state uncertain things as fact; ask clarifying questions \
|
| 53 |
+
or acknowledge uncertainty
|
| 54 |
+
- Create new_memories only for noteworthy things the CURRENT customer said — keep their wording \
|
| 55 |
+
and tone; not every message needs a new memory
|
| 56 |
+
- Choose memory type based on what was said: one-off event (episodic), recurring theme (semantic), \
|
| 57 |
+
current-sounding situation (state), or insight about what helped/hurt in support (procedural)
|
| 58 |
+
- PoC limits: you have no access to billing, CRM, or network systems — guide with questions, \
|
| 59 |
+
logical troubleshooting steps, and reasonable next steps without inventing protocol numbers, \
|
| 60 |
+
discounts, stock levels, or coverage
|
| 61 |
- Respond ONLY with the JSON object — no preamble, no markdown fences
|
| 62 |
"""
|
| 63 |
|
static/index.html
CHANGED
|
@@ -874,13 +874,15 @@
|
|
| 874 |
|
| 875 |
<!-- ── Chat ───────────────────────────────────────── -->
|
| 876 |
<div class="chat-panel">
|
| 877 |
-
<div class="panel-label">// terminal —
|
| 878 |
<div class="messages" id="messages">
|
| 879 |
<div class="msg agent">
|
| 880 |
<div class="msg-label">agente</div>
|
| 881 |
-
<div class="msg-bubble">Olá. Sou o
|
| 882 |
|
| 883 |
-
|
|
|
|
|
|
|
| 884 |
</div>
|
| 885 |
</div>
|
| 886 |
<div class="input-area">
|
|
@@ -888,7 +890,7 @@ Já nasci com algumas memórias de domínio. Pode me dar mais contexto sobre a s
|
|
| 888 |
<textarea
|
| 889 |
id="chat-input"
|
| 890 |
class="chat-input"
|
| 891 |
-
placeholder="
|
| 892 |
rows="1"
|
| 893 |
onkeydown="handleKey(event)"
|
| 894 |
oninput="autoResize(this)"
|
|
|
|
| 874 |
|
| 875 |
<!-- ── Chat ───────────────────────────────────────── -->
|
| 876 |
<div class="chat-panel">
|
| 877 |
+
<div class="panel-label">// terminal — atendimento ISP</div>
|
| 878 |
<div class="messages" id="messages">
|
| 879 |
<div class="msg agent">
|
| 880 |
<div class="msg-label">agente</div>
|
| 881 |
+
<div class="msg-bubble">Olá. Sou o assistente de atendimento desta operadora de internet, TV e telefone.
|
| 882 |
|
| 883 |
+
Uso memórias de falas de clientes anteriores — exatamente como disseram — para tentar ajudar em situações parecidas: lentidão, quedas, fatura, cancelamento, instalação, portabilidade e mais.
|
| 884 |
+
|
| 885 |
+
O painel à direita mostra o que foi lembrado. Conte o seu problema que eu tento orientar com base nisso.</div>
|
| 886 |
</div>
|
| 887 |
</div>
|
| 888 |
<div class="input-area">
|
|
|
|
| 890 |
<textarea
|
| 891 |
id="chat-input"
|
| 892 |
class="chat-input"
|
| 893 |
+
placeholder="descreva seu problema ou dúvida..."
|
| 894 |
rows="1"
|
| 895 |
onkeydown="handleKey(event)"
|
| 896 |
oninput="autoResize(this)"
|