Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions docs/documentacao/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Documentação de Arquitetura — BuildToValue (`mix_btv_code`)

Documentação completa gerada por **análise estática de todo o código-fonte** do
repositório — Rust (14 crates), Python (5 pacotes), TypeScript (2 SPAs React) — e dos
repositório — Rust (14 crates), Python (4 pacotes), TypeScript (2 SPAs React) — e dos
contratos compartilhados em `schemas/`. O objetivo é mapear **como cada
script/módulo/crate/pacote se conecta ao todo**: dependências, fronteiras de linguagem,
fluxos de dados e responsabilidades — base para estudo de arquitetura e refatoramentos.

**Cobertura:** 137 arquivos `.rs` · 87 arquivos `.py` · 160 arquivos `.ts/.tsx`.
**Cobertura:** 137 arquivos `.rs` · 86 arquivos `.py` · 160 arquivos `.ts/.tsx`.

---

Expand All @@ -32,14 +32,14 @@ A documentação está dividida em **diagramas UML** (a espinha visual) e **refe
| 11 | [Modelo de dados (ER)](diagramas/11-modelo-de-dados.md) | Esquema de persistência: produto, ledger, event store, telemetria, sessões PG |
| 12 | [Máquinas de estado](diagramas/12-maquinas-de-estado.md) | RunStatus, permissão, handoff, verdict, degradação, sidecar, sessão web |
| 13 | [Módulos por crate (Rust)](diagramas/13-modulos-rust.md) | Estrutura interna dos 14 crates |
| 14 | [Módulos Python e frontend](diagramas/14-modulos-python-e-frontend.md) | Estrutura interna dos 5 pacotes Python e das 2 SPAs |
| 14 | [Módulos Python e frontend](diagramas/14-modulos-python-e-frontend.md) | Estrutura interna dos 4 pacotes Python e das 2 SPAs |

### Parte II — Referência detalhada (`referencia/`)

| # | Documento | Conteúdo |
|---|---|---|
| 10 | [Inventário Rust](referencia/10-rust-crates.md) | Os 14 crates: propósito, deps, tipos-chave, trait impls, concorrência — com caminhos de arquivo |
| 11 | [Inventário Python](referencia/11-python-pacotes.md) | Os 5 pacotes: classes, ABCs/Protocols, servers gRPC, os 5 agentes |
| 11 | [Inventário Python](referencia/11-python-pacotes.md) | Os 4 pacotes: classes, ABCs/Protocols, servers gRPC, os 5 agentes |
| 12 | [Inventário TypeScript](referencia/12-typescript-frontend.md) | As 2 SPAs: estrutura, contexts, camada `api/`, DTOs, Designer bpmn |
| 13 | [Contratos gRPC e JSON Schemas](referencia/13-contratos-grpc-e-schemas.md) | 4 serviços gRPC (direções), 11 schemas `*.v1`, os 12 templates, hash dual |
| 14 | [Endpoints HTTP](referencia/14-endpoints-http.md) | Tabela completa REST + SSE, com o handler Rust e o consumidor TS |
Expand All @@ -60,7 +60,7 @@ intermediário** de cada módulo (leitura linha-a-linha), incluindo dados locais
| 13 | [Store, proto e sidecar Rust](dados/13-rust-store-proto-sidecar.md) | btv-store, btv-proto, btv-sidecar |
| 14 | [CLI Rust](dados/14-rust-cli.md) | btv-cli (composition root) |
| 15 | [Server e demais Rust](dados/15-rust-server-e-outros.md) | btv-server, btv-tui, btv-golden, btv-contract |
| 16 | [Python](dados/16-python.md) | os 5 pacotes |
| 16 | [Python](dados/16-python.md) | os 4 pacotes |
| 17 | [TypeScript e HTML](dados/17-typescript-e-html.md) | web/, btv-web/ |

### Parte IV — Mapeamentos operacionais (`mapeamentos/`)
Expand Down
2 changes: 1 addition & 1 deletion docs/documentacao/dados/00-mapa-de-dados.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,5 +157,5 @@ Config de tenant SaaS (feature `pg`): variáveis de conexão do pool Postgres (A
| 13 | [Store, proto e sidecar Rust](13-rust-store-proto-sidecar.md) | btv-store, btv-proto, btv-sidecar |
| 14 | [CLI Rust](14-rust-cli.md) | btv-cli (composition root) |
| 15 | [Server e demais Rust](15-rust-server-e-outros.md) | btv-server, btv-tui, btv-golden, btv-contract |
| 16 | [Python](16-python.md) | os 5 pacotes |
| 16 | [Python](16-python.md) | os 4 pacotes |
| 17 | [TypeScript e HTML](17-typescript-e-html.md) | web/, btv-web/ |
16 changes: 1 addition & 15 deletions docs/documentacao/dados/16-python.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,13 @@
# Dicionário de dados — pacotes Python (`python/packages/`)

Mapa de fluxo de dados exaustivo dos 5 pacotes Python do repositório: **btv-eval**,
Mapa de fluxo de dados exaustivo dos 4 pacotes Python do repositório:
**btv-promptforge**, **btv-proto-py**, **btv-review**, **btv-squad**. Cada seção `##`
cobre um arquivo `.py` (os `*_pb2.py`/`*_pb2_grpc.py` gerados só têm os tipos de
mensagem registrados, a partir do proto-fonte). Direções: `entrada`, `saída`,
`intermediário`, `estado`, `config`, `wire`.

---

# Pacote btv-eval

## python/packages/btv-eval/src/btv_eval/__init__.py

Placeholder da Fase 6 — avaliação contínua / A/B / RAG tools. Sem código, só docstring.

| Dado | Tipo | Direção | Origem → Destino | Transformação / observação |
| --- | --- | --- | --- | --- |
| (nenhum) | — | — | — | Módulo VAZIO. Docstring declara intenção futura: consumir telemetria do `btv-store` para comparar prompts/modelos e alimentar o LearningRouter. Nenhum símbolo exportado. |

Fluxo: nenhum — pacote é placeholder documental, sem entrada/saída/estado.

---

# Pacote btv-promptforge

## python/packages/btv-promptforge/src/btv_promptforge/__init__.py
Expand Down
5 changes: 2 additions & 3 deletions docs/documentacao/diagramas/01-visao-geral-e-fronteiras.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ a arquitetura e enumerar os mecanismos de comunicação entre as três linguagen
| Área | Linguagem | Papel |
|---|---|---|
| `crates/` (14 crates, workspace Cargo) | **Rust** | Núcleo: CLI/TUI, gateway LLM, ferramentas, permissões, verify, storage, HTTP, ponte gRPC. **Dono das API keys, disco, rede, processos.** |
| `python/packages/` (5 pacotes, workspace uv) | **Python** | Sidecar de raciocínio: squad multi-agente, PromptForge, review, memória. **Nunca chama LLM direto; nunca toca disco/keys.** |
| `python/packages/` (4 pacotes, workspace uv) | **Python** | Sidecar de raciocínio: squad multi-agente, PromptForge, review, memória. **Nunca chama LLM direto; nunca toca disco/keys.** |
| `btv-web/` | **TS/React 19** | SPA-produto BuildToValue (raiz `/`) — para profissionais não técnicos. |
| `web/` | **TS/React 19** | Console dev/admin (montado em `/dev`, `base: './'`). |
| `schemas/` | **proto + JSON Schema** | Fonte única de contratos (gRPC, `*.v1.schema.json`, 12 templates, fixtures). |
Expand All @@ -21,8 +21,7 @@ Os 14 crates: `btv-cli`, `btv-contract`, `btv-core`, `btv-domain`, `btv-golden`,
`btv-llm`, `btv-proto`, `btv-schemas`, `btv-server`, `btv-sidecar`, `btv-store`,
`btv-tools`, `btv-tui`, `btv-verify`.

Os 5 pacotes Python: `btv-eval`, `btv-promptforge`, `btv-proto-py`, `btv-review`,
`btv-squad`.
Os 4 pacotes Python: `btv-promptforge`, `btv-proto-py`, `btv-review`, `btv-squad`.

---

Expand Down
5 changes: 2 additions & 3 deletions docs/documentacao/diagramas/03-pacotes.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,6 @@ flowchart TB
SQUAD["btv-squad\n«orquestrador + 5 agentes + servers»"]:::pkg
PF["btv-promptforge\n«generators, lint, hashing»"]:::pkg
REVIEW["btv-review\n«4 reviewers, gates, cert»"]:::pkg
EVAL["btv-eval\n«placeholder (vazio)»"]:::pkg
PROTOPY["btv-proto-py\n«stubs gRPC gerados»"]:::gen

SQUAD --> PROTOPY
Expand All @@ -94,8 +93,8 @@ flowchart TB

**Notas.** `btv-proto-py` é o contrato de fio comum (gerado de `schemas/proto/*`, nunca
editado à mão). `btv-review.certification` reusa `btv_promptforge.hashing` (mesmo esquema
canônico do cache-key para `evidence_hash`). `btv-eval` é placeholder honesto (vazio) — a
avaliação A/B real vive em Rust (`btv-schemas::experiment`).
canônico do cache-key para `evidence_hash`). A avaliação A/B real vive em Rust
(`btv-schemas::experiment`); o antigo `btv-eval` (placeholder vazio) foi removido (Onda 5, B4).

---

Expand Down
6 changes: 3 additions & 3 deletions docs/documentacao/diagramas/09-analise-critica.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ leitura estática de todo o código.
sandbox Docker fail-closed, vetter de skills.
- **Honestidade "Nada Fake" codificada:** `fake_marker` no ledger, veredito "sem
significância" no experiment, posições `inferida` na esteira, custo `None` quando não
tabelado, código morto tratado sem fingimento — `forgetting.py` foi removido (código
morto eliminado) e `btv-eval` permanece placeholder vazio explicitamente descopado.
tabelado, código morto tratado sem fingimento — `forgetting.py` e o placeholder vazio
`btv-eval` foram removidos (código morto eliminado, Onda 5 do roadmap).
- **Dualidade de storage sem fork:** SQLite e Postgres+RLS atrás dos **mesmos traits**,
com a suíte `btv-contract` provando paridade (inclusive determinismo de hash).

Expand All @@ -38,7 +38,7 @@ leitura estática de todo o código.
| **`max_autonomy_level` não-wireado** | ~~Campo trafega em `SquadTask` mas é ignorado ponta-a-ponta (ADR 0021).~~ **RESOLVIDO (ADR 0033):** o campo foi REMOVIDO do wire (quebra assinada) — tira a mentira do contrato; a autonomia real segue por agente. | — |
| **Duplicação deliberada do guard de Origin** | `require_local_origin`/`ErrorBody` duplicados entre `btv-server` e `btv-cli::web_agent` (para evitar `server→cli`). | Extrair um crate `btv-web-edge` mínimo com o guard e os DTOs de erro, consumido por ambos. |
| **Ponte async→sync repetida** | Três estratégias em `btv-tools` (thread+runtime, thread de sessão, `std::thread`+condvar) e `rt.block_on` por operação em `PgStore`. | Documentar um ADR de "padrão de ponte" e considerar um helper compartilhado para Sandbox/MCP. |
| **`btv-eval` vazio** | Placeholder que pode enganar quem procura a avaliação. | Implementar o feeder do `LearningRouter` prometido, ou remover e apontar para `btv-schemas::experiment`. |
| **`btv-eval` vazio** | ~~Placeholder que pode enganar quem procura a avaliação.~~ **RESOLVIDO (Onda 5, B4):** pacote removido; a avaliação A/B real é `btv-schemas::experiment`. | — |
| **Designer não aplica ao orquestrador** | `squad.workflow.v1` é "salvo e validado", mas o squad real ainda usa 5 agentes fixos. | Fechar o loop: mapear o grafo salvo para um roster de `PersonaSpec` executável (a infra de roster já existe em `SquadTask`). |
| **Dois frontends com padrão duplicado** | `web/` e `btv-web/` têm `api/client.ts` idêntico e o mesmo padrão Context+reducer. | Considerar um pacote compartilhado de client HTTP/SSE + tipos de DTO (hoje os DTOs são espelhados manualmente em cada SPA). |

Expand Down
10 changes: 5 additions & 5 deletions docs/documentacao/diagramas/14-modulos-python-e-frontend.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 14 — Diagramas de módulo: Python e frontend

Estrutura interna dos 5 pacotes Python e das 2 SPAs. Inventário textual:
Estrutura interna dos 4 pacotes Python e das 2 SPAs. Inventário textual:
[referência 11 (Python)](../referencia/11-python-pacotes.md) e
[referência 12 (TypeScript)](../referencia/12-typescript-frontend.md).

Expand Down Expand Up @@ -49,7 +49,7 @@ flowchart TB
`server.py` é o ponto onde Python-serve-gRPC encontra Python-chama-Rust: injeta os
`Grpc*Client` no `UnifiedOrchestrator`, que compõe os subsistemas e os 5 agentes.

### btv-promptforge · btv-review · btv-proto-py · btv-eval
### btv-promptforge · btv-review · btv-proto-py

```mermaid
flowchart LR
Expand All @@ -64,12 +64,12 @@ flowchart LR
reviewers -.->|derivam de| evidence[(VerificationEvidence)]
end
protopy["btv-proto-py\nstubs gerados de schemas/proto"]
eval["btv-eval\n(placeholder vazio)"]
pf_server --> protopy
```

`hashing.py` é reusado por `btv-review.certification` (mesmo esquema canônico). `btv-eval`
é placeholder; a avaliação A/B real vive no Rust.
`hashing.py` é reusado por `btv-review.certification` (mesmo esquema canônico). A avaliação
A/B real vive no Rust (`btv-schemas::experiment`); o antigo `btv-eval` (placeholder vazio)
foi removido (Onda 5 do roadmap, item B4).

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ Pontos exatos que dependem de `pg` (`#[cfg(feature = "pg")]`): `btv-store/src/li
| **btv-promptforge** | `pydantic>=2`, `grpcio>=1.60`, btv-proto-py | sim (grpcio; pydantic v2 tem core em Rust) |
| **btv-squad** | `pydantic>=2`, `grpcio>=1.60`, btv-proto-py | sim (grpcio) — mas o núcleo de raciocínio (orquestrador/consenso/recall) só usa `pydantic`; `docker` é import **opcional** |
| **btv-review** | `pydantic>=2`, btv-promptforge | **não** (só pydantic; puro) |
| **btv-eval** | (nenhuma) | não (placeholder vazio) |

**Impacto cruzado Python:** mexer em `btv-proto-py` afeta `btv-promptforge` e `btv-squad`
(consumidores dos stubs). Mexer em `btv-promptforge.hashing` afeta `btv-review`
Expand Down
1 change: 0 additions & 1 deletion docs/documentacao/mapeamentos/04-cobertura-de-testes.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ Playwright) + análise de código.
| btv-promptforge | pytest | hashing (paridade), lint, generators |
| btv-review | pytest | gates duros, score, certification |
| btv-proto-py | — | gerado; exercitado indiretamente pelos cross-process do sidecar |
| btv-eval | — | placeholder vazio |

## 4.4 Frontend (SPA × teste)

Expand Down
10 changes: 1 addition & 9 deletions docs/documentacao/referencia/11-python-pacotes.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 11 — Referência: os 5 pacotes Python
# 11 — Referência: os 4 pacotes Python

Workspace uv em `python/` (`pyproject.toml`, membros `packages/*`; dev deps `pytest`,
`grpcio-tools`). Diagrama de classes: ver
Expand Down Expand Up @@ -59,14 +59,6 @@ mão). Dep externa: `grpcio`. Módulos `{core,llm,memory,promptforge,squad}_pb2[

---

## btv-eval — placeholder (vazio)

`python/packages/btv-eval/src/btv_eval/__init__.py` — só docstring, sem código. A avaliação
A/B real vive em Rust (`btv-schemas::experiment`); a avaliação runtime do squad é
`btv_squad/evaluation.py::ContinuousEvaluator`.

---

## btv-squad — o sidecar multi-agente

`python/packages/btv-squad/src/btv_squad/`. Deps: `pydantic`, `grpcio`, `btv-proto-py`.
Expand Down
13 changes: 0 additions & 13 deletions python/packages/btv-eval/pyproject.toml

This file was deleted.

5 changes: 0 additions & 5 deletions python/packages/btv-eval/src/btv_eval/__init__.py

This file was deleted.

2 changes: 0 additions & 2 deletions python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ dependencies = [
"btv-squad",
"btv-promptforge",
"btv-review",
"btv-eval",
"btv-proto-py",
]

Expand All @@ -21,7 +20,6 @@ members = ["packages/*"]
btv-squad = { workspace = true }
btv-promptforge = { workspace = true }
btv-review = { workspace = true }
btv-eval = { workspace = true }
btv-proto-py = { workspace = true }

[tool.pytest.ini_options]
Expand Down
8 changes: 0 additions & 8 deletions python/uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading