Skip to content

68eaep codex/implementar persistência de contexto baseada em run #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 213 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
213 commits
Select commit Hold shift + click to select a range
fea3bbd
oi
lucasandrioli Apr 17, 2025
08de6a2
oi
lucasandrioli Apr 17, 2025
861c6ea
novo
lucasandrioli Apr 28, 2025
d7f3772
ois
lucasandrioli Apr 29, 2025
e78fab8
uuhum
lucasandrioli Apr 29, 2025
2ac58ec
hm
lucasandrioli Apr 29, 2025
7a5a41a
opa
lucasandrioli Apr 29, 2025
5f112c2
hm
lucasandrioli Apr 29, 2025
a80b9f8
hm
lucasandrioli Apr 29, 2025
9ef64c1
uhum
lucasandrioli Apr 29, 2025
8e99670
uuhum
lucasandrioli May 1, 2025
d5481f2
hm
lucasandrioli May 1, 2025
53235d6
AHAM
lucasandrioli May 1, 2025
da4cc0c
uhum
lucasandrioli May 2, 2025
3b6251f
alou2/muda1
lucasandrioli May 5, 2025
3054f58
refactor2
lucasandrioli May 5, 2025
9a5e63f
uhum
lucasandrioli May 5, 2025
b921471
aham
lucasandrioli May 5, 2025
24fd4c4
agora foi
lucasandrioli May 5, 2025
a994f74
opa
lucasandrioli May 5, 2025
0a301ba
sem ptt
lucasandrioli May 5, 2025
382a9e5
aham
lucasandrioli May 5, 2025
68b88a5
uhmmm
lucasandrioli May 9, 2025
8a00fb6
Update marlene.ts
lucasandrioli May 9, 2025
85be274
valor
lucasandrioli May 13, 2025
e95cd3a
hmfoi
lucasandrioli May 13, 2025
2fa87d3
modo
lucasandrioli May 13, 2025
c401548
camera_verification
lucasandrioli May 13, 2025
1e9a215
maisrobusto
lucasandrioli May 13, 2025
e787150
utilsemarlene
lucasandrioli May 14, 2025
cb3141d
novo
lucasandrioli May 14, 2025
fe51e9f
ois
lucasandrioli May 14, 2025
b7f4838
ois
lucasandrioli May 15, 2025
ea2483a
ois
lucasandrioli May 15, 2025
da86616
oi
lucasandrioli May 15, 2025
019791f
opa
lucasandrioli May 15, 2025
0cd19f2
Adiciona linha de teste para PR do Codex
lucasandrioli May 17, 2025
b2bcfc7
feat: add implementations for all utils tools in marlene
lucasandrioli May 17, 2025
9b3d1d3
Merge pull request #2 from lucasandrioli/codex/atualizar-marlene-ts-p…
lucasandrioli May 17, 2025
7def472
feat: add loan simulator
lucasandrioli May 17, 2025
54fa6a9
Merge pull request #3 from lucasandrioli/codex/develop-loan-simulator…
lucasandrioli May 17, 2025
b474b53
Integrate loan simulator into Marlene agent
lucasandrioli May 17, 2025
39f0a25
Merge pull request #4 from lucasandrioli/codex/integrate-loan-simulat…
lucasandrioli May 17, 2025
fad13a2
Rename create_structure script
lucasandrioli May 17, 2025
1544cdb
Merge pull request #5 from lucasandrioli/codex/rename-create-structur…
lucasandrioli May 17, 2025
43ecc5d
Update README with loan simulator section
lucasandrioli May 17, 2025
1122ace
Merge pull request #6 from lucasandrioli/codex/update-readme-md-with-…
lucasandrioli May 17, 2025
71ceec9
fix: remove unused vars and satisfy lint
lucasandrioli May 17, 2025
3e7d271
Merge branch 'minhas-mudancas' into codex/fix-unused-variables-after-…
lucasandrioli May 17, 2025
1fee050
Merge pull request #7 from lucasandrioli/codex/fix-unused-variables-a…
lucasandrioli May 17, 2025
d9bba3d
Implement connection context and fix imports
lucasandrioli May 17, 2025
b67a449
Merge pull request #8 from lucasandrioli/codex/create-connectionconte…
lucasandrioli May 17, 2025
650f5c5
fix contexts for client
lucasandrioli May 17, 2025
e955060
Merge pull request #9 from lucasandrioli/codex/fix-import-errors-in-u…
lucasandrioli May 17, 2025
81a4b51
fix build issues
lucasandrioli May 17, 2025
a9cbd54
Merge pull request #10 from lucasandrioli/codex/fix-import-errors-in-…
lucasandrioli May 17, 2025
f9408a1
docs: clarify env vars and install steps
lucasandrioli May 17, 2025
7365ae4
Merge pull request #11 from lucasandrioli/codex/fix-import-errors-in-…
lucasandrioli May 17, 2025
58b2b36
Add env example and update setup instructions
lucasandrioli May 17, 2025
c6e29da
feat: mark simple hooks as client
lucasandrioli May 17, 2025
3a62fe9
feat: add client directive and env check
lucasandrioli May 17, 2025
e6f8062
Merge pull request #12 from lucasandrioli/codex/add-env-example-file-…
lucasandrioli May 17, 2025
5a9512a
Merge pull request #14 from lucasandrioli/codex/modify-usewebrtcconne…
lucasandrioli May 17, 2025
3190d31
Merge pull request #13 from lucasandrioli/codex/add-use-client-direct…
lucasandrioli May 17, 2025
a07f2bc
Add @xstate/fsm dependency
lucasandrioli May 17, 2025
806ec0d
Merge pull request #15 from lucasandrioli/codex/declare-xstate-fsm-in…
lucasandrioli May 17, 2025
3ccc19f
maintain connection stability
lucasandrioli May 17, 2025
5c7a96a
Merge pull request #17 from lucasandrioli/codex/fix-webrtc-connection…
lucasandrioli May 17, 2025
cefdd37
fix: use backend simulator for Marlene
lucasandrioli May 17, 2025
b9c8654
Merge pull request #18 from lucasandrioli/codex/refactor-m-quina-de-e…
lucasandrioli May 17, 2025
cda769c
fix: close camera automatically after verification
lucasandrioli May 17, 2025
b6d0dee
Merge pull request #19 from lucasandrioli/codex/adicionar-fechamento-…
lucasandrioli May 17, 2025
565e4e9
Update Marlene flow with improved transitions
lucasandrioli May 17, 2025
e004a8f
Merge pull request #39 from lucasandrioli/codex/verify-marlene-s-stat…
lucasandrioli May 17, 2025
e285fbf
Advance to camera step after benefit check
lucasandrioli May 17, 2025
4c08929
Merge pull request #40 from lucasandrioli/codex/verify-marlene-s-stat…
lucasandrioli May 17, 2025
c6d1cb0
Add LLM-based state recommendation
lucasandrioli May 18, 2025
9b56a94
Merge pull request #41 from lucasandrioli/codex/verify-marlene-s-stat…
lucasandrioli May 18, 2025
e7db98b
Improve state handling in handleUserMessage
lucasandrioli May 18, 2025
e5e8337
Merge pull request #42 from lucasandrioli/codex/refactor-handleuserme…
lucasandrioli May 18, 2025
268ab8d
feat: detect early exit intent
lucasandrioli May 18, 2025
116132c
Merge pull request #43 from lucasandrioli/codex/extend-extractentitie…
lucasandrioli May 18, 2025
070c69c
chore: remove unused loan simulator module
lucasandrioli May 18, 2025
bc5d544
Merge pull request #44 from lucasandrioli/codex/delete-redundant-loan…
lucasandrioli May 18, 2025
c5cc396
feat: add LLM powered loan backend
lucasandrioli May 18, 2025
8b15a02
Merge pull request #45 from lucasandrioli/codex/melhorar-fake-backend
lucasandrioli May 18, 2025
a1e8b87
Ignore data directory
lucasandrioli May 18, 2025
e6e3bf6
Merge pull request #46 from lucasandrioli/codex/editar-gitignore-para…
lucasandrioli May 18, 2025
0c7fc28
Add Jest setup and unit tests for loan consult API
lucasandrioli May 18, 2025
e1c9e11
Merge pull request #47 from lucasandrioli/codex/configure-jest-or-vit…
lucasandrioli May 18, 2025
c5b502a
Validate ConsultaBeneficio before caching
lucasandrioli May 18, 2025
b0ce759
Merge pull request #48 from lucasandrioli/codex/validate-consultabene…
lucasandrioli May 18, 2025
1f89db3
Allow shorter benefit numbers
lucasandrioli May 18, 2025
cc59f45
Merge pull request #49 from lucasandrioli/codex/fix-consultation-hang…
lucasandrioli May 18, 2025
c9b727c
Clarify benefit consult flow
lucasandrioli May 18, 2025
08ea652
Merge pull request #50 from lucasandrioli/codex/fix-consultation-hang…
lucasandrioli May 18, 2025
0d02717
fix jest openai mock initialization
lucasandrioli May 18, 2025
51a1d78
Merge pull request #51 from lucasandrioli/codex/declare-createmock-wi…
lucasandrioli May 18, 2025
f857e4d
Add newline to agent config index
lucasandrioli May 18, 2025
95265f0
Merge pull request #52 from lucasandrioli/codex/append-newline-to-ind…
lucasandrioli May 18, 2025
6efce2e
docs: add testing instructions
lucasandrioli May 18, 2025
6fc9f8e
Merge pull request #53 from lucasandrioli/codex/update-readme-to-incl…
lucasandrioli May 18, 2025
eb7e43f
docs: expand setup instructions
lucasandrioli May 18, 2025
5748764
Merge pull request #54 from lucasandrioli/codex/update-readme-with-se…
lucasandrioli May 18, 2025
907d01f
Add trailing newline to create_structure.sh
lucasandrioli May 18, 2025
9794745
Merge pull request #55 from lucasandrioli/codex/add-newline-at-end-of…
lucasandrioli May 18, 2025
a92717e
Fix gitignore trailing text
lucasandrioli May 18, 2025
e4a01d2
Merge pull request #56 from lucasandrioli/codex/edit-gitignore-to-rem…
lucasandrioli May 18, 2025
6be39cf
style: add trailing newline to next.config
lucasandrioli May 18, 2025
6a56e31
Merge pull request #57 from lucasandrioli/codex/add-newline-to-next-c…
lucasandrioli May 18, 2025
a17cae3
Add trailing newline to create_structure.sh
lucasandrioli May 18, 2025
e310abb
Merge pull request #58 from lucasandrioli/codex/append-newline-to-cre…
lucasandrioli May 18, 2025
a69325e
chore: add .nvmrc for node 18
lucasandrioli May 18, 2025
6517537
Merge pull request #59 from lucasandrioli/codex/add-nvmrc-or-engines-…
lucasandrioli May 18, 2025
5c50de6
chore(package): rename browserlist config key
lucasandrioli May 18, 2025
6ca0ffb
Merge pull request #61 from lucasandrioli/codex/update-browserlist-in…
lucasandrioli May 18, 2025
703b32d
Add Node engine requirement
lucasandrioli May 18, 2025
ae6d238
Merge pull request #63 from lucasandrioli/codex/add-engines-field-to-…
lucasandrioli May 18, 2025
cd0866c
Add time-based greeting tool for Marlene
lucasandrioli May 18, 2025
ccc4e54
Merge pull request #64 from lucasandrioli/codex/criar-tool-para-sauda…
lucasandrioli May 18, 2025
8d1329b
Improve state machine logging
lucasandrioli May 18, 2025
dbd16bc
Merge pull request #65 from lucasandrioli/codex/adicionar-logs-de-con…
lucasandrioli May 18, 2025
bfacf4f
Remove test loan animation trigger
lucasandrioli May 18, 2025
bdc2758
Merge pull request #66 from lucasandrioli/codex/fix-premature-animati…
lucasandrioli May 18, 2025
b4a4ee1
Fix build errors and update agent logic
lucasandrioli May 18, 2025
e47b1d7
Merge pull request #67 from lucasandrioli/codex/analisar-c-digo-para-…
lucasandrioli May 18, 2025
fb5aa91
Add verification machine tests and fix cache cleanup
lucasandrioli May 18, 2025
8ccf197
Merge pull request #69 from lucasandrioli/codex/add-tests-for-verific…
lucasandrioli May 18, 2025
ffb09fe
Add conversation utils tests and fix loan consult test mocking
lucasandrioli May 18, 2025
c260f77
Merge pull request #70 from lucasandrioli/codex/create-test-file-for-…
lucasandrioli May 18, 2025
af2a49c
Improve state transitions
lucasandrioli May 18, 2025
fd5d245
Merge pull request #71 from lucasandrioli/codex/refactor-conversation…
lucasandrioli May 18, 2025
6ae5cc4
Add time-based greeting tool
lucasandrioli May 18, 2025
2aa8a8f
Merge pull request #72 from lucasandrioli/codex/adicionar-sauda-o-aut…
lucasandrioli May 18, 2025
882ae7c
Add verification API and integrate camera workflow
lucasandrioli May 18, 2025
58ec491
Merge pull request #73 from lucasandrioli/codex/implement-identity-ve…
lucasandrioli May 18, 2025
0480ae7
Improve camera verification flow
lucasandrioli May 18, 2025
0189a71
Merge branch 'back' into codex/implement-identity-verification-api-fl…
lucasandrioli May 18, 2025
533f30b
Merge pull request #74 from lucasandrioli/codex/implement-identity-ve…
lucasandrioli May 18, 2025
2abc529
Emit cancellation camera event in verification hook
lucasandrioli May 18, 2025
d670fe5
Merge pull request #76 from lucasandrioli/codex/add-handling-for-veri…
lucasandrioli May 18, 2025
bb8598e
Dispatch camera closing event
lucasandrioli May 18, 2025
9259b40
Merge pull request #77 from lucasandrioli/codex/dispatch-camera-closi…
lucasandrioli May 18, 2025
ca1aece
Handle verification API errors
lucasandrioli May 18, 2025
75f1746
Merge pull request #78 from lucasandrioli/codex/handle-verification-e…
lucasandrioli May 18, 2025
434fe0b
retry response after rate limit
lucasandrioli May 18, 2025
5d67746
Merge pull request #80 from lucasandrioli/codex/fix-animation-and-age…
lucasandrioli May 18, 2025
b0a2998
Change record state trigger condition
lucasandrioli May 18, 2025
734b1e9
Merge pull request #81 from lucasandrioli/codex/modify-condition-for-…
lucasandrioli May 18, 2025
a4224a2
Reset conversation context on connect and disconnect
lucasandrioli May 18, 2025
9f626ce
Merge pull request #82 from lucasandrioli/codex/integrate-resetconver…
lucasandrioli May 18, 2025
2999d8f
advance state when recommended
lucasandrioli May 19, 2025
0a262ce
Merge pull request #83 from lucasandrioli/codex/fix-state-machine-pro…
lucasandrioli May 19, 2025
700fdda
fix: handle agent function calls in simple WebRTC
lucasandrioli May 19, 2025
25f6f9d
Merge pull request #84 from lucasandrioli/codex/corrigir-script-de-ma…
lucasandrioli May 19, 2025
4e6e351
Add CI workflow
lucasandrioli May 19, 2025
6f5971b
Merge pull request #85 from lucasandrioli/codex/create-ci-workflow-wi…
lucasandrioli May 19, 2025
28e9a3d
feat: fallback for AbortSignal timeout
lucasandrioli May 19, 2025
0ff2e79
Merge pull request #86 from lucasandrioli/codex/check-for-abortsignal…
lucasandrioli May 19, 2025
5c9e183
Remove API key logs
lucasandrioli May 19, 2025
6cec926
Merge pull request #87 from lucasandrioli/codex/remove-console-logs-w…
lucasandrioli May 19, 2025
5fb6836
test: add WebRTC function_call handling
lucasandrioli May 19, 2025
8cc9af5
Merge pull request #88 from lucasandrioli/codex/add-jest-test-for-use…
lucasandrioli May 19, 2025
8b905fb
feat: handle unknown tool calls
lucasandrioli May 19, 2025
a68356c
Merge pull request #89 from lucasandrioli/codex/handle-unknown-functi…
lucasandrioli May 19, 2025
7f45f7b
fix greeting timezone
lucasandrioli May 19, 2025
73fc093
Merge pull request #90 from lucasandrioli/codex/verificar-erro-no-c-l…
lucasandrioli May 19, 2025
e353248
Add document prompt in verification
lucasandrioli May 19, 2025
71e0755
Merge pull request #91 from lucasandrioli/codex/update-verificationco…
lucasandrioli May 19, 2025
852881b
Add face verification endpoint and update camera context
lucasandrioli May 19, 2025
ba89fea
Merge pull request #92 from lucasandrioli/codex/implement-face-verifi…
lucasandrioli May 19, 2025
325bbce
Refactor speaking state and add footer styles
lucasandrioli May 19, 2025
1fed99c
Merge pull request #93 from lucasandrioli/codex/analisar-troca-de-cor…
lucasandrioli May 19, 2025
051437c
chore: add logging for footer color changes
lucasandrioli May 19, 2025
66b4afb
Merge branch 'back' into codex/analisar-troca-de-cores-para-fala-do-a…
lucasandrioli May 19, 2025
7c38b17
Merge pull request #94 from lucasandrioli/codex/analisar-troca-de-cor…
lucasandrioli May 19, 2025
8335f3a
Add repository guidelines and setup script
lucasandrioli May 19, 2025
92656f9
Merge pull request #95 from lucasandrioli/codex/analisar-c-digo-e-cri…
lucasandrioli May 19, 2025
3ab2714
Add logging for speaker changes and footer classes
lucasandrioli May 19, 2025
523fece
Merge branch 'back' into codex/analisar-troca-de-cores-para-fala-do-a…
lucasandrioli May 19, 2025
441f7ef
Merge pull request #97 from lucasandrioli/codex/analisar-troca-de-cor…
lucasandrioli May 19, 2025
bebe020
Add setup script and improve instructions
lucasandrioli May 19, 2025
d539ffb
Merge branch 'back' into codex/analisar-c-digo-e-criar-agent-md-o4d77q
lucasandrioli May 19, 2025
cd265fc
Merge pull request #98 from lucasandrioli/codex/analisar-c-digo-e-cri…
lucasandrioli May 19, 2025
81d4a9e
Update AGENT.md
lucasandrioli May 19, 2025
91fabb4
back md
lucasandrioli May 19, 2025
e28ecfe
Add playground with mock contexts
lucasandrioli May 20, 2025
d2dfe09
Merge pull request #100 from lucasandrioli/codex/create-playground-di…
lucasandrioli May 20, 2025
27bd2fa
Add setup script
lucasandrioli May 20, 2025
adc3342
Merge pull request #101 from lucasandrioli/7mw92i-codex/create-playgr…
lucasandrioli May 20, 2025
94439b4
Expose context objects for mocking
lucasandrioli May 20, 2025
2407fcc
Merge pull request #102 from lucasandrioli/codex/fix-useconnection-er…
lucasandrioli May 20, 2025
9c69ab8
Remove playground test buttons and handle simulation events
lucasandrioli May 20, 2025
d3f9c24
Merge pull request #103 from lucasandrioli/codex/corrigir-bot-es-e-fu…
lucasandrioli May 20, 2025
55e0578
reorder
lucasandrioli May 27, 2025
14721a3
docs: update app url
lucasandrioli May 27, 2025
7aa9013
Merge pull request #120 from lucasandrioli/codex/entender-sistema-fak…
lucasandrioli May 27, 2025
bd8ee4c
Update setup script
lucasandrioli May 27, 2025
f4e09e3
Merge pull request #121 from lucasandrioli/codex/update-setup.sh-script
lucasandrioli May 27, 2025
4ac6d1a
Refactor footer color transitions using currentColor
lucasandrioli May 28, 2025
0923bb8
Merge pull request #122 from lucasandrioli/codex/revisar-animação-e-t…
lucasandrioli May 28, 2025
88a8308
feat(playground): implement mock connection provider
lucasandrioli May 28, 2025
d798849
Merge pull request #123 from lucasandrioli/codex/implement-mock-conve…
lucasandrioli May 28, 2025
a5a030a
docs: add intro and recent changes section
lucasandrioli May 28, 2025
30e362c
Merge pull request #124 from lucasandrioli/codex/add-introduction-to-…
lucasandrioli May 28, 2025
4f30587
Add AGENTS update check
lucasandrioli May 28, 2025
be72aaf
Merge pull request #125 from lucasandrioli/codex/create-check-agents-…
lucasandrioli May 28, 2025
ed2367f
docs: add contributing guidelines
lucasandrioli May 28, 2025
8b5a6c6
Merge pull request #126 from lucasandrioli/codex/update-readme-or-cre…
lucasandrioli May 28, 2025
3e46859
feat: add optional pre-commit hook
lucasandrioli May 28, 2025
411d6a7
Merge pull request #127 from lucasandrioli/codex/add-pre-commit-hook-…
lucasandrioli May 28, 2025
dcf9460
Add conversation state machine and refactor utils
lucasandrioli May 28, 2025
f37765b
Merge pull request #128 from lucasandrioli/codex/create-and-integrate…
lucasandrioli May 28, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .codex/setup.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
#!/usr/bin/env bash
set -euo pipefail

NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \ . "$NVM_DIR/nvm.sh"
nvm use 18

npm ci

if [ ! -f .env.local ] && [ -f .env.example ]; then
cp .env.example .env.local
fi

npm test || true
npm run lint || true
4 changes: 4 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
OPENAI_API_KEY=your-server-key
NEXT_PUBLIC_OPENAI_API_KEY=your-client-key

NEXT_PUBLIC_USE_LLM_BACKEND=false
17 changes: 17 additions & 0 deletions .github/workflows/check-agents.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: Check AGENTS documentation

on:
push:
branches: [main]
pull_request:

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 18
- name: Verify AGENTS documentation updated
run: node scripts/check-agents-updated.js
20 changes: 20 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
name: CI

on:
push:
branches: [main]
pull_request:

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 18
cache: 'npm'
cache-dependency-path: package-lock.json
- run: npm install
- run: npm test
- run: npm run lint
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,13 @@ yarn-error.log*

# env files (can opt-in for committing if needed)
.env*
!.env.example

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts
todo.md
data/
todo.md
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
18
77 changes: 77 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Documentação dos Agentes

## Introdução
Este projeto é mantido principalmente por um colaborador sem formação formal em desenvolvimento. Este arquivo serve para acumular o conhecimento adquirido sobre o código e registrar sua evolução. Para isso existe a subseção **O que mudou recentemente**, que lista de forma cronológica as alterações mais relevantes.

## Visão Geral
Este repositório contém uma aplicação demo que simula um atendimento de crédito consignado via voz. A pasta `src/app/simple` apresenta a interface web utilizada durante a conversa e toda a lógica voltada para a agente **Marlene**.

Marlene é um agente de voz configurado em `src/app/agentConfigs/marlene.ts`. Ela interage em português, com fala pausada e linguagem extremamente simples para atender principalmente idosos com baixa literacia digital. O comportamento dela envolve uma máquina de estados conversacional, ferramentas próprias e um backend de simulação de empréstimos.

## O que mudou recentemente
- Julho/2024: adicionada opcao de pre-commit hook com testes e lint.
- Agosto/2024: gerenciamento da conversa movido para uma XState machine dedicada.
- Junho/2024: adicionadas orientacoes de contribuicao em CONTRIBUTING.md.
- Maio/2024: projeto iniciado como demonstração do agente Marlene e fluxo de concessão de crédito consignado.


## Principais Arquivos
- `src/app/agentConfigs/marlene.ts` – define a personalidade de Marlene, suas ferramentas e como cada chamada de ferramenta processa a conversa.
- `src/app/agentConfigs/utils.ts` – contém o contexto global da conversa, extração de entidades e funções para avançar a máquina de estados.
- `src/app/loanSimulator/index.ts` – backend falso que gera dados de benefício e simulações de empréstimo.
- `src/app/simple/machines/verificationMachine.ts` – máquina de estados para a verificação facial via câmera.
- `src/app/simple/machines/conversationMachine.ts` – controla o fluxo principal da conversa.

## Máquina de Estados da Conversa
O fluxo da conversa é guiado por nove estados principais. A cada mensagem do usuário, `processUserInputAsync` extrai entidades (nome, número de benefício, valor desejado etc.) e `conversationMachine` decide para qual estado seguir.

1. **1_greeting** – Marlene cumprimenta e começa a entender a necessidade do cliente.
2. **2_identify_need** – coleta nome, forma de tratamento preferida e finalidade do empréstimo.
3. **4_benefit_verification** – confirma o número do benefício e consulta limites.
4. **5_camera_verification** – verifica identidade por câmera antes de simular valores.
5. **6_loan_simulation** – apresenta opções de empréstimo conforme os dados coletados.
6. **7_understanding_check** – usa `verify_understanding` para garantir que o cliente compreendeu as condições.
7. **8_confirmation** – registra a intenção de contratar e gera documentação acessível.
8. **9_closing** – encerra o atendimento de forma cordial.
9. **10_early_exit** – caminho para quando o usuário desiste ou não tem interesse.

`recordStateChange` persiste cada transição no contexto global (em `utils.ts`), permitindo retomar a conversa de onde parou se necessário. A função `resetConversationContext` restaura o estado inicial (`1_greeting`).

## Ferramentas Disponíveis
Marlene utiliza várias ferramentas declaradas em `marlene.ts`:
- **animate_loan_value** – destaca valores de empréstimo na interface.
- **open_camera** / **close_camera** – controla a câmera para verificação de identidade.
- **verify_understanding** – avalia se o cliente entendeu o impacto do empréstimo.
- **simplify_financial_explanation** – traduz conceitos complexos para analogias simples.
- **consult_benefit** – consulta limites de benefício no backend simulado.
- **create_accessible_documentation** – gera um resumo (áudio, SMS ou impresso) para o cliente.

A lógica de cada ferramenta fica em `toolLogic` dentro do próprio `marlene.ts`.

## Verificação por Câmera
A verificação facial é controlada por `verificationMachine.ts`, uma máquina de estados XState independente. O fluxo é `idle → preparing → analyzing → verifying → completed`, com transições para `failed` em caso de erro ou se o tempo exceder 15 s em qualquer estágio inicial.

## Backend de Empréstimo
O arquivo `loanSimulator/index.ts` gera dados fictícios de benefício e simulações. Quando a variável de ambiente `NEXT_PUBLIC_USE_LLM_BACKEND=true` é definida, o simulador passa a chamar `/api/loan/consult`, onde um modelo de linguagem produz respostas mais detalhadas e consistentes. Os resultados são armazenados em `data/llm-benefit-cache.json` para reutilização.

## Executando o Projeto
Crie um arquivo `.env.local` com as chaves da OpenAI e demais variáveis:
```
OPENAI_API_KEY=sk-...
NEXT_PUBLIC_OPENAI_API_KEY=sk-...
NEXT_PUBLIC_USE_LLM_BACKEND=true
```
Instale as dependências e execute em modo de desenvolvimento:
```
npm install
npm run dev
```
A aplicação estará disponível em `http://localhost:3000/`.

Para garantir a qualidade, use:
```
npm test # executa a suíte Jest
npm run lint # verifica o código com eslint
```

Com esta estrutura, Marlene conduz o usuário por todo o processo de crédito consignado de maneira humanizada, utilizando a máquina de estados e o backend de simulação para fornecer respostas coerentes mesmo sem conexão real com sistemas bancários.
24 changes: 24 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Contributing

Thank you for your interest in improving this project! To keep track of changes over time, please follow these guidelines when submitting a pull request.

## Document your changes

Whenever you make a significant modification to any source code or tests, add a short entry under the **O que mudou recentemente** section in [`AGENTS.md`](AGENTS.md). The entry should briefly describe what was changed and the month/year.

## Continuous integration check

The workflow [`check-agents.yml`](.github/workflows/check-agents.yml) verifies that `AGENTS.md` was updated whenever files inside `src/` or `__tests__/` change. If you forget to update the file, your pull request will fail this check with a message reminding you to document your changes.

Run the existing tests and linter with `npm test` and `npm run lint` before opening a PR.


## Optional pre-commit hook

A script is available at `scripts/git-hooks/pre-commit` that runs `npm test` and `npm run lint`, the same checks executed in CI. To have it run automatically before each commit, create a symbolic link:

```
ln -s ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
```

This step is optional but recommended for frequent contributors.
58 changes: 48 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,49 @@ You should be able to use this repo to prototype your own multi-agent realtime v

## Setup

- This is a Next.js typescript app
- Install dependencies with `npm i`
- Add your `OPENAI_API_KEY` to your env
- Start the server with `npm run dev`
- Open your browser to [http://localhost:3000](http://localhost:3000) to see the app. It should automatically connect to the `simpleExample` Agent Set.

## Configuring Agents
Configuration in `src/app/agentConfigs/simpleExample.ts`
### Requisitos
- Node.js >=18 <21.
- Este projeto é uma aplicação Next.js com TypeScript.

### Instalação
- Execute `npm install` para instalar as dependências.

### Configuração do ambiente
- Copie `.env.example` para `.env.local` e preencha as variáveis abaixo:
- `OPENAI_API_KEY` – chave usada pelo backend.
- `NEXT_PUBLIC_OPENAI_API_KEY` – chave visível no frontend.
- `NEXT_PUBLIC_USE_LLM_BACKEND` – quando `true` o backend utiliza o LLM para gerar dados fictícios; nesse caso o diretório `data/` será criado automaticamente para armazenar `llm-benefit-cache.json`.
- Após editar `package.json`, rode `npm install` novamente caso novas dependências (como `encoding`) tenham sido adicionadas.

### Servidor de desenvolvimento
- Inicie com `npm run dev` e acesse [http://localhost:3000](http://localhost:3000). O app conecta automaticamente ao Agent Set `simpleExample`.
- Para testar somente a interface, sem precisar de conexão com a API, use [http://localhost:3000/playground](http://localhost:3000/playground). Esse modo roda offline e serve para experimentos de UI.

### Loan simulator backend
Marlene consome o backend falso em `src/app/loanSimulator`. Rodar `npm run dev` com o Agent Set padrão (`marlene`) utiliza essas funções para simulações de empréstimo e ofertas Itaú.
Com `NEXT_PUBLIC_USE_LLM_BACKEND=true`, o simulador passa a chamar `/api/loan/consult`, gerando dados consistentes via modelo OpenAI. O resultado fica em `data/llm-benefit-cache.json` e o diretório `data/` é criado automaticamente se ainda não existir.

## Testes e lint
- `npm test` executa a suíte Jest.
- `npm run lint` roda o linter do projeto.

## Build para produção
- Gere o build com `npm run build`.
- Em seguida inicie o servidor com `npm start`.

## Integração contínua
Este repositório possui um workflow de CI em `.github/workflows/ci.yml` que instala as dependências,
executa `npm test` e `npm run lint` usando Node.js 18. O fluxo utiliza o cache do `actions/setup-node`
para agilizar as execuções.

Além disso, o workflow `.github/workflows/check-agents.yml` garante que qualquer mudança em arquivos de
código seja acompanhada de uma atualização no `AGENTS.md`. Caso o arquivo de documentação não seja
alterado quando arquivos em `src/` ou `__tests__/` forem modificados, o PR falhará com uma mensagem
orientando a atualizar o `AGENTS.md`.

## Configurando agentes
Escolha um dos arquivos em `src/app/agentConfigs` para definir o comportamento dos agentes ou crie o seu próprio.
O exemplo abaixo mostra a configuração em `src/app/agentConfigs/simpleExample.ts`:
```javascript
import { AgentConfig } from "@/app/types";
import { injectTransferTools } from "./utils";
Expand Down Expand Up @@ -54,8 +89,8 @@ This fully specifies the agent set that was used in the interaction shown in the
- [frontDeskAuthentication](src/app/agentConfigs/frontDeskAuthentication) Guides the user through a step-by-step authentication flow, confirming each value character-by-character, authenticates the user with a tool call, and then transfers to another agent. Note that the second agent is intentionally "bored" to show how to prompt for personality and tone.
- [customerServiceRetail](src/app/agentConfigs/customerServiceRetail) Also guides through an authentication flow, reads a long offer from a canned script verbatim, and then walks through a complex return flow which requires looking up orders and policies, gathering user context, and checking with `o1-mini` to ensure the return is eligible. To test this flow, say that you'd like to return your snowboard and go through the necessary prompts!

### Defining your own agents
- You can copy these to make your own multi-agent voice app! Once you make a new agent set config, add it to `src/app/agentConfigs/index.ts` and you should be able to select it in the UI in the "Scenario" dropdown menu.
### Definindo seus próprios agentes
- Você pode copiar esses exemplos para criar seu próprio voice app multiagente! Após criar uma nova configuração, adicione-a em `src/app/agentConfigs/index.ts` para que ela apareça no menu "Scenario" da interface.
- To see how to define tools and toolLogic, including a background LLM call, see [src/app/agentConfigs/customerServiceRetail/returns.ts](src/app/agentConfigs/customerServiceRetail/returns.ts)
- To see how to define a detailed personality and tone, and use a prompt state machine to collect user information step by step, see [src/app/agentConfigs/frontDeskAuthentication/authentication.ts](src/app/agentConfigs/frontDeskAuthentication/authentication.ts)
- To see how to wire up Agents into a single Agent Set, see [src/app/agentConfigs/frontDeskAuthentication/index.ts](src/app/agentConfigs/frontDeskAuthentication/index.ts)
Expand All @@ -70,3 +105,6 @@ This fully specifies the agent set that was used in the interaction shown in the
## Core Contributors
- Noah MacCallum - [noahmacca](https://x.com/noahmacca)
- Ilan Bigio - [ibigio](https://github.com/ibigio)

## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on documenting your code changes and running the checks. Frequent contributors may want to install the optional pre-commit hook described there.
34 changes: 34 additions & 0 deletions __tests__/conversationMachine.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import { conversationMachine } from '@/app/simple/machines/conversationMachine';

describe('conversationMachine', () => {
test('benefit and value from greeting jumps to loan simulation', () => {
let state = conversationMachine.initialState;
state = conversationMachine.transition(state, { type: 'BENEFIT_AND_VALUE_PROVIDED' });
expect(state.value).toBe('6_loan_simulation');
});

test('name leads to identify_need', () => {
let state = conversationMachine.initialState;
state = conversationMachine.transition(state, { type: 'NAME_DETECTED' });
expect(state.value).toBe('2_identify_need');
});

test('benefit confirmed without camera goes to camera verification', () => {
let state = {
value: '4_benefit_verification',
context: { cameraVerified: false }
} as any;
state = conversationMachine.transition(state, { type: 'BENEFIT_CONFIRMED' });
expect(state.value).toBe('5_camera_verification');
});

test('camera verification completes flow', () => {
let state = {
value: '5_camera_verification',
context: { cameraVerified: false }
} as any;
state = conversationMachine.transition(state, { type: 'CAMERA_VERIFIED' });
expect(state.value).toBe('6_loan_simulation');
expect(state.context.cameraVerified).toBe(true);
});
});
50 changes: 50 additions & 0 deletions __tests__/conversationUtils.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
import { processUserInput, exportContext, resetConversationContext, setCameraVerified } from '@/app/agentConfigs/utils';

beforeEach(() => {
resetConversationContext();
});

describe('processUserInput', () => {
test('extracts entities and updates context', () => {
const phrase = 'Meu nome é Joao. Meu benefício é 123456. Quero um empréstimo de R$ 50.000 para reforma. Estou com meu filho.';
const result = processUserInput(phrase);

expect(result.entities).toEqual(expect.objectContaining({
name: 'Joao',
benefitNumber: '123456',
requestedAmount: 'R$ 50.000',
purpose: 'reforma',
hasCompanion: true,
companionType: 'filho(a)'
}));
expect(result.recommendedState).toBe('6_loan_simulation');

const context = exportContext();
expect(context.name).toBe('Joao');
expect(context.benefitNumber).toBe('123456');
expect(context.requestedAmount).toBe('R$ 50.000');
expect(context.purpose).toBe('reforma');
expect(context.hasCompanion).toBe(true);
expect(context.companionType).toBe('filho(a)');
expect(context.confirmedEntities.has('benefitNumber')).toBe(true);
});

test('recommends loan simulation when camera is verified', () => {
setCameraVerified(true);
const phrase = 'Meu benefício é 654321 e quero um empréstimo de R$ 10.000';
const result = processUserInput(phrase);
expect(result.recommendedState).toBe('6_loan_simulation');
});

test('context persists across multiple inputs', () => {
processUserInput('Meu nome é Maria');
let context = exportContext();
expect(context.name).toBe('Maria');
expect(context.benefitNumber).toBeUndefined();

processUserInput('Número do benefício 111222');
context = exportContext();
expect(context.name).toBe('Maria');
expect(context.benefitNumber).toBe('111222');
});
});
Loading