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.

Files changed (3) hide show
  1. README.md +17 -12
  2. agent.py +25 -15
  3. static/index.html +6 -4
README.md CHANGED
@@ -1,17 +1,18 @@
1
  # Agent Memory — Fase 1 (Baseline)
2
 
3
- Agente de varejo com sistema de memória observável.
4
- Chat à esquerda · Armazém de memórias à direita.
 
5
 
6
  ## Estrutura
7
 
8
  ```
9
  agent_memory/
10
  ├── main.py # FastAPI app
11
- ├── agent.py # Lógica do agente + Claude API
12
  ├── memory_store.py # ChromaDB + decay heurístico
13
  ├── models.py # Pydantic models
14
- ├── seeds.py # Memórias iniciais (7 seeds de varejo)
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 ANTHROPIC_API_KEY
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 | Cor | Decay/dia | Uso |
59
- |-------------|---------|-----------|----------------------------------|
60
- | episódica | azul | 0.03 | Eventos passados específicos |
61
- | semântica | roxo | 0.005 | Padrões abstraídos de experiência|
62
- | estado | laranja | 0.15 | Fatos atuais (voláteis) |
63
- | procedimental| verde | 0.002 | Como fazer algo (estável) |
 
 
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 an intelligent retail business advisor agent for a supermarket chain.
15
- You help with decisions about product mix, inventory management, promotions, and store operations.
 
16
 
17
- You have access to the following memories from past experience and learning:
 
 
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 natural language response to the user (detailed and actionable)",
26
  "memories_used": ["id1", "id2"],
27
  "new_memories": [
28
  {{
29
- "content": "Complete description of what should be remembered",
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 past event with temporal context ("last holiday, sales rose 40%")
40
- - semantic → general pattern abstracted from experience ("holidays increase footfall")
41
- - state → current fact that may change ("supplier X is delayed this week")
42
- - procedural → stable how-to knowledge ("restock order must be placed by Thursday noon")
43
 
44
  ─────────────────────────────────────────────
45
  GUIDELINES:
46
- - Use only memories that are genuinely relevant to the current query
47
- - List only the IDs of memories you actually referenced in your response
48
- - Only create new memories for information that is genuinely worth retaining
49
- - Not every message needs a new memory
50
- - Be specific and actionable; reference memory content explicitly when relevant
 
 
 
 
 
 
 
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 — agente de varejo</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 agente de inteligência de varejo. Posso te ajudar com decisões de mix de produtos, gestão de estoque, promoções e operações da loja.
882
 
883
- nasci com algumas memórias de domínio. Pode me dar mais contexto sobre a situação atual da loja, eventos próximos, ou perguntar sobre decisões de mix de produtos.</div>
 
 
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="mensagem para o agente..."
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)"