From a73525ccc4f6417d9cab8bd7a78ef301d75c8fbb Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 18:45:29 +0000 Subject: [PATCH] refactor(python): remove o placeholder vazio btv-eval (Onda 5, B4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit O pacote `btv-eval` era um placeholder vazio (só docstring, nada o importava) — "podia enganar quem procura a avaliação" (§9.2). A avaliação A/B real vive no Rust (`btv-schemas::experiment` / `btv experiment`); a avaliação runtime do squad é `btv_squad/evaluation.py::ContinuousEvaluator`. Remover é o caminho honesto (item B4 do roadmap). - Removido `python/packages/btv-eval/`; tirado de `python/pyproject.toml` (dependência + source do workspace); `uv.lock` regenerado (`uv lock`). - docs/documentacao reconciliadas: "5 pacotes Python" → "4" e contagem `.py` 87 → 86 (README, diagramas/01,03,14, dados/00,16, referencia/11, mapeamentos/01,04); 09-analise-critica marca o item RESOLVIDO. Verificação local: `uv run pytest` 200/200; nenhuma referência a btv-eval sobrou fora das docs (que agora descrevem a remoção). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01DkWvx5G1XqRZwybmCErshc --- docs/documentacao/README.md | 10 +++++----- docs/documentacao/dados/00-mapa-de-dados.md | 2 +- docs/documentacao/dados/16-python.md | 16 +--------------- .../diagramas/01-visao-geral-e-fronteiras.md | 5 ++--- docs/documentacao/diagramas/03-pacotes.md | 5 ++--- .../documentacao/diagramas/09-analise-critica.md | 6 +++--- .../diagramas/14-modulos-python-e-frontend.md | 10 +++++----- .../01-dependencias-build-features.md | 1 - .../mapeamentos/04-cobertura-de-testes.md | 1 - .../documentacao/referencia/11-python-pacotes.md | 10 +--------- python/packages/btv-eval/pyproject.toml | 13 ------------- .../packages/btv-eval/src/btv_eval/__init__.py | 5 ----- python/pyproject.toml | 2 -- python/uv.lock | 8 -------- 14 files changed, 20 insertions(+), 74 deletions(-) delete mode 100644 python/packages/btv-eval/pyproject.toml delete mode 100644 python/packages/btv-eval/src/btv_eval/__init__.py diff --git a/docs/documentacao/README.md b/docs/documentacao/README.md index 1fa881d..2017cfc 100644 --- a/docs/documentacao/README.md +++ b/docs/documentacao/README.md @@ -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`. --- @@ -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 | @@ -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/`) diff --git a/docs/documentacao/dados/00-mapa-de-dados.md b/docs/documentacao/dados/00-mapa-de-dados.md index b509d77..dbb1bcc 100644 --- a/docs/documentacao/dados/00-mapa-de-dados.md +++ b/docs/documentacao/dados/00-mapa-de-dados.md @@ -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/ | diff --git a/docs/documentacao/dados/16-python.md b/docs/documentacao/dados/16-python.md index 65b561f..80cb008 100644 --- a/docs/documentacao/dados/16-python.md +++ b/docs/documentacao/dados/16-python.md @@ -1,6 +1,6 @@ # 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`, @@ -8,20 +8,6 @@ mensagem registrados, a partir do proto-fonte). Direções: `entrada`, `saída`, --- -# 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 diff --git a/docs/documentacao/diagramas/01-visao-geral-e-fronteiras.md b/docs/documentacao/diagramas/01-visao-geral-e-fronteiras.md index be8fc61..cf6fc68 100644 --- a/docs/documentacao/diagramas/01-visao-geral-e-fronteiras.md +++ b/docs/documentacao/diagramas/01-visao-geral-e-fronteiras.md @@ -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). | @@ -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`. --- diff --git a/docs/documentacao/diagramas/03-pacotes.md b/docs/documentacao/diagramas/03-pacotes.md index 31c31b3..39d37a8 100644 --- a/docs/documentacao/diagramas/03-pacotes.md +++ b/docs/documentacao/diagramas/03-pacotes.md @@ -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 @@ -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). --- diff --git a/docs/documentacao/diagramas/09-analise-critica.md b/docs/documentacao/diagramas/09-analise-critica.md index 0d8dfd7..e781018 100644 --- a/docs/documentacao/diagramas/09-analise-critica.md +++ b/docs/documentacao/diagramas/09-analise-critica.md @@ -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). @@ -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). | diff --git a/docs/documentacao/diagramas/14-modulos-python-e-frontend.md b/docs/documentacao/diagramas/14-modulos-python-e-frontend.md index 07e5f19..905cb13 100644 --- a/docs/documentacao/diagramas/14-modulos-python-e-frontend.md +++ b/docs/documentacao/diagramas/14-modulos-python-e-frontend.md @@ -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). @@ -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 @@ -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). --- diff --git a/docs/documentacao/mapeamentos/01-dependencias-build-features.md b/docs/documentacao/mapeamentos/01-dependencias-build-features.md index 90ba7eb..fa035d0 100644 --- a/docs/documentacao/mapeamentos/01-dependencias-build-features.md +++ b/docs/documentacao/mapeamentos/01-dependencias-build-features.md @@ -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` diff --git a/docs/documentacao/mapeamentos/04-cobertura-de-testes.md b/docs/documentacao/mapeamentos/04-cobertura-de-testes.md index 3801429..a954f4d 100644 --- a/docs/documentacao/mapeamentos/04-cobertura-de-testes.md +++ b/docs/documentacao/mapeamentos/04-cobertura-de-testes.md @@ -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) diff --git a/docs/documentacao/referencia/11-python-pacotes.md b/docs/documentacao/referencia/11-python-pacotes.md index 910c727..4446233 100644 --- a/docs/documentacao/referencia/11-python-pacotes.md +++ b/docs/documentacao/referencia/11-python-pacotes.md @@ -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 @@ -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`. diff --git a/python/packages/btv-eval/pyproject.toml b/python/packages/btv-eval/pyproject.toml deleted file mode 100644 index 096e034..0000000 --- a/python/packages/btv-eval/pyproject.toml +++ /dev/null @@ -1,13 +0,0 @@ -[project] -name = "btv-eval" -version = "0.1.0" -description = "Avaliação contínua e A/B testing da plataforma BuildToValue — implementação na Fase 6" -requires-python = ">=3.11" -dependencies = [] - -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - -[tool.hatch.build.targets.wheel] -packages = ["src/btv_eval"] diff --git a/python/packages/btv-eval/src/btv_eval/__init__.py b/python/packages/btv-eval/src/btv_eval/__init__.py deleted file mode 100644 index 666ba63..0000000 --- a/python/packages/btv-eval/src/btv_eval/__init__.py +++ /dev/null @@ -1,5 +0,0 @@ -"""Avaliação contínua, A/B testing e RAG tools — placeholder da Fase 6. - -Consumirá a telemetria do `btv-store` para comparar prompts/modelos e -alimentar o LearningRouter do squad. -""" diff --git a/python/pyproject.toml b/python/pyproject.toml index 2953beb..f665fdb 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -7,7 +7,6 @@ dependencies = [ "btv-squad", "btv-promptforge", "btv-review", - "btv-eval", "btv-proto-py", ] @@ -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] diff --git a/python/uv.lock b/python/uv.lock index 75e9560..aa790ab 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -4,7 +4,6 @@ requires-python = ">=3.11" [manifest] members = [ - "btv-eval", "btv-promptforge", "btv-proto-py", "btv-python-workspace", @@ -21,11 +20,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" }, ] -[[package]] -name = "btv-eval" -version = "0.1.0" -source = { editable = "packages/btv-eval" } - [[package]] name = "btv-promptforge" version = "0.1.0" @@ -59,7 +53,6 @@ name = "btv-python-workspace" version = "0.1.0" source = { virtual = "." } dependencies = [ - { name = "btv-eval" }, { name = "btv-promptforge" }, { name = "btv-proto-py" }, { name = "btv-review" }, @@ -74,7 +67,6 @@ dev = [ [package.metadata] requires-dist = [ - { name = "btv-eval", editable = "packages/btv-eval" }, { name = "btv-promptforge", editable = "packages/btv-promptforge" }, { name = "btv-proto-py", editable = "packages/btv-proto-py" }, { name = "btv-review", editable = "packages/btv-review" },