llm-dev-core 1.0.0__tar.gz → 1.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/.github/workflows/ci.yml +3 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/.github/workflows/publish.yml +3 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/CHANGELOG.md +178 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/Makefile +7 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/PKG-INFO +1 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0003-secure-base-contract.md +6 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0006-ci-pack-contract.md +16 -2
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0007-cache-ratelimit-contract.md +5 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0009-parser-io-contract.md +24 -1
- llm_dev_core-1.3.0/docs/decisions/0010-diff-engine-contract.md +60 -0
- llm_dev_core-1.3.0/docs/decisions/0011-agent-loop-contract.md +70 -0
- llm_dev_core-1.3.0/docs/metrics/evidence.html +1 -0
- llm_dev_core-1.3.0/docs/verification/BASELINE.md +69 -0
- llm_dev_core-1.3.0/docs/verification/METODOLOGIA.md +117 -0
- llm_dev_core-1.3.0/docs/verification/PERF.md +42 -0
- llm_dev_core-1.3.0/docs/verification/baseline.json +491 -0
- llm_dev_core-1.3.0/docs/verification/perf.json +56 -0
- llm_dev_core-1.3.0/packages/agent-loop/pyproject.toml +15 -0
- llm_dev_core-1.3.0/packages/agent-loop/src/agent_loop/__init__.py +12 -0
- llm_dev_core-1.3.0/packages/agent-loop/src/agent_loop/loop.py +128 -0
- llm_dev_core-1.3.0/packages/agent-loop/tests/test_agent_loop.py +100 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/cache-ratelimit/src/cache_ratelimit/providers.py +12 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/cache-ratelimit/tests/test_cache_ratelimit.py +22 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/src/ci_pack/metrics.py +112 -5
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/tests/test_ci_pack.py +69 -0
- llm_dev_core-1.3.0/packages/diff-engine/pyproject.toml +15 -0
- llm_dev_core-1.3.0/packages/diff-engine/src/diff_engine/__init__.py +11 -0
- llm_dev_core-1.3.0/packages/diff-engine/src/diff_engine/diff.py +112 -0
- llm_dev_core-1.3.0/packages/diff-engine/tests/test_diff_engine.py +67 -0
- llm_dev_core-1.3.0/packages/llm-client/src/llm_client/pricing.py +46 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/test_pricing_cache.py +19 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/src/parser_io/readers.py +22 -21
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/tests/test_parser_io.py +57 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/src/secure_base/detectors.py +11 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/tests/test_secure_base.py +33 -1
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/pyproject.toml +4 -2
- llm_dev_core-1.3.0/scripts/verification_baseline.py +956 -0
- llm_dev_core-1.3.0/scripts/verification_clauses.py +256 -0
- llm_dev_core-1.3.0/scripts/verification_perf.py +470 -0
- llm_dev_core-1.3.0/scripts/verification_sensitivity.py +278 -0
- llm_dev_core-1.3.0/tests/test_verification_baseline.py +240 -0
- llm_dev_core-1.3.0/tests/test_verification_perf.py +84 -0
- llm_dev_core-1.0.0/docs/metrics/evidence.html +0 -1
- llm_dev_core-1.0.0/packages/llm-client/src/llm_client/pricing.py +0 -22
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/.gitignore +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/.python-version +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/ARCHITECTURE.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/README.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0000-stack.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0001-llm-client-contract.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0002-schema-validate-contract.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0004-test-kit-dataset-contract.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0005-web-api-base-contract.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/decisions/0008-bot-base-contract.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/metrics/README.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/docs/runbooks/README.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/clock.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/digest.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/runner.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/schedule.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/src/bot_base/store.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/bot-base/tests/test_bot_base.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/cache-ratelimit/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/cache-ratelimit/src/cache_ratelimit/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/cache-ratelimit/src/cache_ratelimit/ratelimit.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/src/ci_pack/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/src/ci_pack/job.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/ci-pack/src/ci_pack/lints.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/scripts/record_tape_opencode.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/cache.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/client.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/models.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/provider.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/providers/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/providers/openai_compat.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/providers/opencode_cli.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/replay.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/src/llm_client/span.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/cassettes/complete-opencode--big-pickle-2.jsonl +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/conftest.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/test_openai_compat.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/test_real_tape.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/test_replay.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/llm-client/tests/test_span.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/src/parser_io/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/src/parser_io/io.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/parser-io/src/parser_io/models.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/schema-validate/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/schema-validate/src/schema_validate/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/schema-validate/src/schema_validate/registry.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/schema-validate/src/schema_validate/validate.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/schema-validate/tests/test_schema_validate.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/src/secure_base/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/src/secure_base/findings.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/src/secure_base/profile.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/secure-base/src/secure_base/redact.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/src/test_kit/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/src/test_kit/criteria.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/src/test_kit/dataset.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/src/test_kit/runner.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/test-kit/tests/test_test_kit.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/pyproject.toml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/src/web_api_base/__init__.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/src/web_api_base/app.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/src/web_api_base/errors.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/src/web_api_base/llm_route.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/src/web_api_base/response.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/packages/web-api-base/tests/test_web_api_base.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/scripts/check_consumers.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/scripts/collect_metrics.py +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/scripts/compat_check.sh +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/templates/consumer-readme.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/templates/core-consumer.yml +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/templates/eval-dataset.jsonl +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/templates/prompt.md +0 -0
- {llm_dev_core-1.0.0 → llm_dev_core-1.3.0}/templates/retrofit-issue.md +0 -0
|
@@ -14,6 +14,9 @@ jobs:
|
|
|
14
14
|
runs-on: ubuntu-latest
|
|
15
15
|
steps:
|
|
16
16
|
- uses: actions/checkout@v4
|
|
17
|
+
with:
|
|
18
|
+
fetch-depth: 0 # las cláusulas leen `git show v1.0.0:` — hace falta historia
|
|
19
|
+
fetch-tags: true
|
|
17
20
|
- uses: astral-sh/setup-uv@v6
|
|
18
21
|
with:
|
|
19
22
|
python-version-file: .python-version
|
|
@@ -13,6 +13,9 @@ jobs:
|
|
|
13
13
|
runs-on: ubuntu-latest
|
|
14
14
|
steps:
|
|
15
15
|
- uses: actions/checkout@v4
|
|
16
|
+
with:
|
|
17
|
+
fetch-depth: 0 # las cláusulas leen `git show v1.0.0:` — hace falta historia
|
|
18
|
+
fetch-tags: true
|
|
16
19
|
- uses: astral-sh/setup-uv@v6
|
|
17
20
|
with:
|
|
18
21
|
python-version-file: .python-version
|
|
@@ -1,7 +1,185 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v1.3.0 — 2026-11-20 (semana 21, C13)
|
|
4
|
+
|
|
5
|
+
- **`agent-loop` (C13, ADR-11): el loop mínimo con puerta humana.** Proponer
|
|
6
|
+
(cerebro inyectado), confirmar (`confirm` antes de cada efecto), ejecutar
|
|
7
|
+
(herramientas con nombre), registrar (trace auditable). El error de una herramienta
|
|
8
|
+
no mata la corrida; el rechazo termina sin insistir; el presupuesto de pasos es
|
|
9
|
+
visible (`paro="presupuesto"`), no un timeout.
|
|
10
|
+
- La hoja no cambia: `agent-loop` no depende de ningún módulo del core ni llama
|
|
11
|
+
modelos — como `bot-base`, el determinismo es por construcción (D4) y el cerebro
|
|
12
|
+
(un cierre sobre `LlmClient`, o un guion en tests) se compone en el consumidor.
|
|
13
|
+
- Primer consumidor: `checklist-walker` (sem. 21), que camina un checklist sobre un
|
|
14
|
+
repo real con herramientas de lectura (`exists/read/grep`) y reporta con LLM
|
|
15
|
+
validado.
|
|
16
|
+
- 172 tests en el core (165 + 7 de agent-loop).
|
|
17
|
+
|
|
18
|
+
## v1.2.0 — 2026-11-20 (semana 19, C12)
|
|
19
|
+
|
|
20
|
+
- **`diff-engine` (C12, ADR-10): comparación estructural determinista.** Nace vencida
|
|
21
|
+
(su seed estaba calendariado en la sem. 19 junto a la verificación que pagó esa
|
|
22
|
+
semana) y con su primer consumidor: `cassette-diff`, que mide la **deriva del
|
|
23
|
+
modelo** entre dos grabaciones del mismo prompt con la misma entrada (demo real:
|
|
24
|
+
similitud 0.6283, un hunk, `drift_menor`).
|
|
25
|
+
- Contrato del módulo (ADR-10): `diff_records` campo a campo con **volátiles
|
|
26
|
+
declarados y listados** (timestamp, ids y latencias no son deriva; esconder que se
|
|
27
|
+
ignoran, sí sería mentir), `diff_text` en hunks `cambiada/agregada/eliminada`,
|
|
28
|
+
`text_similarity` en [0, 1]. Determinista por construcción (difflib, D4); la hoja
|
|
29
|
+
no cambia: stdlib + pydantic, sin dependencias del core.
|
|
30
|
+
- Qué NO es: similitud semántica — eso es `vector-core` (C11), que **sigue vencida
|
|
31
|
+
desde la sem. 16** (deuda registrada en el issue #2).
|
|
32
|
+
- 165 tests en el core (157 + 8 de diff-engine).
|
|
33
|
+
|
|
3
34
|
La versión es la del paquete `llm-dev-core`. El historial arranca con el **hito v1.0 (semana 13)**: hasta 0.10.0 el core era `0.x` y podía romperse sin aviso (D3); desde v1.0.0 los contratos son estables.
|
|
4
35
|
|
|
36
|
+
## v1.1.1 — 2026-11-19 (semana 15, issue #1)
|
|
37
|
+
|
|
38
|
+
- **cache-ratelimit: la poda del `CachedProvider` es amortizada.** `_prune` escaneaba
|
|
39
|
+
todo el store en cada `complete()` (issue #1): el hit costaba 1.8 µs con una entrada
|
|
40
|
+
y 45 µs con 2 500 (ratio 25×). Ahora la poda corre a lo sumo una vez por ventana de
|
|
41
|
+
`ttl/2` y el coste del hit deja de crecer con el tamaño del store: **ratio 1.0×**
|
|
42
|
+
medido por `make verify-perf` — la cláusula `cache_hit_scaling` pasa a `TRUE` y el
|
|
43
|
+
baseline de rendimiento queda en **7 `TRUE`, 0 `FALSE`**.
|
|
44
|
+
- Sin cambio de contrato observable: una entrada vencida nunca se devuelve (la
|
|
45
|
+
frescura siempre se comprueba por entrada); solo puede quedar en memoria hasta la
|
|
46
|
+
próxima poda (~1.5×`ttl`). ADR-7 §2 queda enmendado con la decisión y su medición,
|
|
47
|
+
sin tocar la línea del ancla preexistente.
|
|
48
|
+
- El test de poda existente sigue verde sin editar; uno nuevo fija la cadencia
|
|
49
|
+
(ventana cerrada ⇒ no poda) y la frescura por entrada (vencida pedida ⇒ miss fresco).
|
|
50
|
+
- 157 tests en el core, 79 en los 12 consumidores — todos verdes contra el core
|
|
51
|
+
modificado, `check_consumers` OK ×12.
|
|
52
|
+
|
|
53
|
+
## v1.1 — 2026-11-19 (verificación objetiva, semana 14, F0-F4)
|
|
54
|
+
|
|
55
|
+
- **F0: baseline de verificación medible.** `scripts/verification_baseline.py` mide nueve
|
|
56
|
+
cláusulas contractuales contra artefactos reales y escribe `docs/verification/baseline.json`
|
|
57
|
+
más `docs/verification/BASELINE.md` (`make verify-baseline`). Ninguna cifra del informe está
|
|
58
|
+
escrita a mano: el veredicto se deriva de la medición.
|
|
59
|
+
Resultado inicial: 4 `TRUE`, 2 `PARCIAL`, 3 `FALSE`.
|
|
60
|
+
- **F1: prueba de sensibilidad.** `scripts/verification_sensitivity.py` inyecta nueve
|
|
61
|
+
rupturas deliberadas (parse no determinista, body desplazado, validador permisivo,
|
|
62
|
+
detector que marca todo, `Schedule` siempre dispuesto, `Span` con 19 campos, …) y exige
|
|
63
|
+
que la medición correspondiente cambie. Las nueve se detectan; si alguna dejara de
|
|
64
|
+
detectarse, el script sale 1.
|
|
65
|
+
- **F2: los tres defectos de código quedan pagos** (el baseline pasó de 4 `TRUE` a 7):
|
|
66
|
+
- `parser-io`: una sección Markdown sin cuerpo ya no desaparece en silencio. Se conserva
|
|
67
|
+
con `body == ""`, `body_tokens == 0` y `line_end == line_start`.
|
|
68
|
+
- `parser-io`: la ruta H1-fallback (documento sin H2) ahora respeta el mismo contrato de
|
|
69
|
+
líneas que la ruta H2 — `body == lines[line_start:line_end]` en el **100%** de las
|
|
70
|
+
secciones del corpus real (187/187, antes 184/186). El texto del heading ya no se
|
|
71
|
+
duplica dentro de `body` y el frontmatter de los prompts tampoco.
|
|
72
|
+
- `secure-base`: el detector `phone` exige forma escrita (`+`, paréntesis o separador).
|
|
73
|
+
Dejaba de marcar `uuid` y `epoch` como teléfono (2 de 10 negativos duros). El coste
|
|
74
|
+
asumido y documentado: un teléfono de 10 dígitos sin separador ya no se marca.
|
|
75
|
+
- ADR-3 §2 y ADR-9 §2 quedan actualizados con el contrato corregido y su oráculo.
|
|
76
|
+
- Sin cambios rompientes para los consumidores: los 12 repos siguen verdes contra el core
|
|
77
|
+
modificado y `check_consumers` da OK en los 12.
|
|
78
|
+
|
|
79
|
+
### F2.1 — el cierre del cierre
|
|
80
|
+
|
|
81
|
+
Un cuestionamiento del propio F2 encontró cuatro huecos. Todos están pagos:
|
|
82
|
+
|
|
83
|
+
- **Las cláusulas ya no son del instrumento.** `scripts/verification_clauses.py` registra,
|
|
84
|
+
por medición, el archivo y la línea del contrato que se cita, y su tipo lo decide
|
|
85
|
+
`git show v1.0.0:<archivo>` — no el autor. Resultado: 4 cláusulas `PREEXISTENTE`
|
|
86
|
+
(campos del span, tres formas de JSON, determinismo D4, TTL/ráfaga/idempotencia),
|
|
87
|
+
3 `DECISION v1.1` (contrato de líneas, heading sin cuerpo, forma escrita de `phone`)
|
|
88
|
+
y 2 `CRITERIO DE PROYECTO`, que viven ahora en `docs/verification/METODOLOGIA.md`.
|
|
89
|
+
Verificar una decisión de v1.1 no dice nada sobre el pasado: el informe lo dice.
|
|
90
|
+
- **Cita falsa corregida.** El baseline citaba "ADR-1 §10" para los campos del span; §10
|
|
91
|
+
no existe (son §1–§6) y la lista está en la línea 58. La medición ya no hardcodea 20:
|
|
92
|
+
parsea esa lista del ADR y compara conjuntos, así que un campo nuevo o borrado se ve sin
|
|
93
|
+
editar el script.
|
|
94
|
+
- **La autorreferencia de F0 queda escrita en el artefacto**, no solo en la conversación:
|
|
95
|
+
`BASELINE.md` incluye una sección *Historial de cláusulas* que admite que el `FALSE` de
|
|
96
|
+
F0 en `empty_heading` se apoyaba en una cláusula inventada.
|
|
97
|
+
- **El trade-off de `phone` tiene ancla ejecutable.** `sec-check/tests/test_tradeoff.py`
|
|
98
|
+
fija las dos direcciones: `+57 300 123 4567` se redacta y `assert_redacted` lo ve;
|
|
99
|
+
`3001234567` sin separador pasa limpio, y el test lo declara hueco conocido.
|
|
100
|
+
- **El sentinel `line_start == 0` lo cubre el consumidor.** `content-ray/src/content_ray/main.py`
|
|
101
|
+
renderiza `max(1, line_start)` para no imprimir `L0`, y tres tests nuevos fijan el panel,
|
|
102
|
+
el lookup de `--sample doc:1` y que los documentos con heading no cambian de rango.
|
|
103
|
+
- Sensibilidad: la ruptura de `span_contract` pasó de "19 vs 20" a "falta `cost_usd`",
|
|
104
|
+
que es el fallo real ahora que el número sale del ADR.
|
|
105
|
+
- 134 tests en el core (107 de v1.0), 78 en los 12 consumidores, `check_consumers` OK ×12.
|
|
106
|
+
|
|
107
|
+
### F3 — los dos `FALSE` restantes, y por qué eran del instrumento
|
|
108
|
+
|
|
109
|
+
Los dos `FALSE` de F2 no eran datos malos: eran criterios malos, y ninguno de los dos
|
|
110
|
+
podía volverse `TRUE` nunca. El baseline queda en **9 `TRUE`, 0 `PARCIAL`, 0 `FALSE`**.
|
|
111
|
+
|
|
112
|
+
- **`cost_usd` devolvía 0 para todo.** La tabla de precios tiene una sola entrada,
|
|
113
|
+
`big-pickle`, pero los cassettes registran `opencode/big-pickle`: el nombre no
|
|
114
|
+
coincidía, la búsqueda fallaba y caía al `(0.0, 0.0)` por defecto. Peor: ese
|
|
115
|
+
defecto silenciaba el caso grave — un modelo de pago sin pricedar reportaba $0 y
|
|
116
|
+
el cap de costo nunca disparaba. `llm_client.pricing` gana `price_key()` (resuelve
|
|
117
|
+
el prefijo de proveedor) y `model_price_known()`, que separa "gratis" de
|
|
118
|
+
"desconocido". El criterio de F0 (`$0.0000` en la página ⇒ `FALSE`) declaraba roto
|
|
119
|
+
un dato correcto: para `big-pickle` el 0 **sí** estaba medido.
|
|
120
|
+
- **La página de evidencia separa los tres ceros que confundía.** Antes mostraba
|
|
121
|
+
`$0.0000` en las doce filas sin decir de dónde salía. Ahora separa `llamadas (span)`
|
|
122
|
+
de `llamadas (cassette)`, publica tokens in/out, y rotula cada costo:
|
|
123
|
+
`(spans)`, `(cassette · modelo en tabla de precios)`, `costo desconocido` o
|
|
124
|
+
`sin datos de llamada`. Un cassette no es un span: trae `usage` real del proveedor
|
|
125
|
+
pero no pasó por el pipeline del core, así que no tiene `latency_ms` ni
|
|
126
|
+
`retry_count` y no se suma en un único "llamadas". Resultado: 40 llamadas y
|
|
127
|
+
190 004 / 12 393 tokens que antes no aparecían en ninguna parte.
|
|
128
|
+
- **`evidence-api` y `fleet-bot` rotulan el costo** con la misma regla, y sus README
|
|
129
|
+
se actualizaron con la salida real (12 consumidores, no 10).
|
|
130
|
+
- **`docs_claims` ya no depende de una constante.** F0 fijaba
|
|
131
|
+
`verificado_por_ejecucion: 0` escrito a mano, así que el veredicto no dependía de
|
|
132
|
+
nada medido. Ahora la cifra se clasifica antes de exigirle una ejecución: de las
|
|
133
|
+
98 de los 12 READMEs, 12 son claims de contrato y 12 coinciden con su oráculo;
|
|
134
|
+
las otras 86 son puertos, códigos HTTP, fechas, porcentajes, transcripciones o
|
|
135
|
+
números de semana, que no afirman nada sobre el comportamiento del sistema.
|
|
136
|
+
- **Dos README tenían cifras falsas** y el oráculo las cazó: `content-ray` decía
|
|
137
|
+
"12 ADRs" cuando hay 10, y `core-smoke` decía "107 tests" cuando ya no eran 107.
|
|
138
|
+
La segunda no se corrige poniéndole el número nuevo: se sustituye por el comando,
|
|
139
|
+
porque un conteo de tests envejece igual de rápido. La metodología dice ahora que
|
|
140
|
+
una cifra de contrato que depende de un número cambiante se escribe como comando.
|
|
141
|
+
- **Las rupturas de F1 seguían mintiendo.** `evidence_self_audit` y `docs_claims`
|
|
142
|
+
fijaban claves que la medición reescrita ya no usaba, así que "pasaban" sin
|
|
143
|
+
comprobar nada. Ahora el harness nombra cada ruptura por la medición que rompe
|
|
144
|
+
(`idempotence`, no `parse_determinism`) y un test exige que toda medición tenga la
|
|
145
|
+
suya y que siga detectándola. La de `evidence_self_audit` cambió de sentido: ahora
|
|
146
|
+
rompe con un modelo fuera de la tabla de precios, que es el fallo real.
|
|
147
|
+
- ADR-6 §2 registra el cambio de contrato: "de cada fuente que falte, cuenta cero"
|
|
148
|
+
sigue valiendo para el conteo y era falsa para la interpretación.
|
|
149
|
+
- 152 tests en el core, 78 en los 12 consumidores, `check_consumers` OK ×12,
|
|
150
|
+
sensibilidad 10/10.
|
|
151
|
+
|
|
152
|
+
### F4 — "optimizado" gana oráculo: la forma es contrato, el número no
|
|
153
|
+
|
|
154
|
+
La pregunta "¿está optimizado?" no tenía respuesta verificable: §4 del baseline
|
|
155
|
+
excluía la calidad y ninguna cifra medía velocidad. `scripts/verification_perf.py`
|
|
156
|
+
(`make verify-perf`) abre esa dimensión bajo tres reglas nuevas
|
|
157
|
+
(`docs/verification/METODOLOGIA.md` §7):
|
|
158
|
+
|
|
159
|
+
1. **Un tiempo absoluto no es contrato** (depende del hardware): lo verificable es
|
|
160
|
+
la forma — el coste de una operación O(1) no crece con el estado.
|
|
161
|
+
2. **Pisos de guardarrail ~100× por debajo de lo medido** para seis operaciones del
|
|
162
|
+
camino caliente (parser, detectores, validación, span, precio, rate-limit): solo
|
|
163
|
+
una regresión estructural los rompe.
|
|
164
|
+
3. **La deuda visible vale más que el verde fingido**: un `FALSE` crónico se publica
|
|
165
|
+
con su acción abierta.
|
|
166
|
+
|
|
167
|
+
Resultado inicial: **6 `TRUE`, 1 `FALSE`**. El `FALSE` es `cache_hit_scaling`: el
|
|
168
|
+
coste de un hit de `CachedProvider` crece con el tamaño del store (1.8 µs con 1
|
|
169
|
+
entrada vs ~45 µs con 2 500; ratio ~25×, umbral 10×) porque `_prune` escanea todo el
|
|
170
|
+
diccionario en cada `complete()`. Fix registrado en el issue #1 (sem. 15); ningún
|
|
171
|
+
contrato del baseline se rompe por eso.
|
|
172
|
+
|
|
173
|
+
- Siete cláusulas nuevas en `scripts/verification_clauses.py`, todas
|
|
174
|
+
`CRITERIO DE PROYECTO` ancladas a §7 (el tag v1.0.0 no contiene esas líneas).
|
|
175
|
+
- El test del registro de cláusulas pasa de igualdad exacta a subconjunto: el
|
|
176
|
+
registro ya tiene dos familias (contratos y perf) y cada una exige la suya.
|
|
177
|
+
- `docs/verification/{perf.json,PERF.md}` se escriben en cada corrida; el JSON de
|
|
178
|
+
perf no es sync-testeable (los tiempos varían), así que la suite exige estructura,
|
|
179
|
+
veredictos derivados de la medición y anclas — no cifras congeladas.
|
|
180
|
+
- 156 tests en el core (152 de F3 + 4 de perf), baseline regenerado con el corpus
|
|
181
|
+
ampliado (su corpus incluye los scripts y tests nuevos, como manda su contrato).
|
|
182
|
+
|
|
5
183
|
## v1.0 — 2026-10-08 (hito v1.0, semana 13)
|
|
6
184
|
|
|
7
185
|
- **Primer semver mayor: los contratos pasan a estables.** Diez módulos (ADR-0 a
|
|
@@ -2,7 +2,7 @@ PY := uv run python
|
|
|
2
2
|
PYTEST := uv run pytest
|
|
3
3
|
CHECK := scripts/check_consumers.py
|
|
4
4
|
|
|
5
|
-
.PHONY: validate validate-consumer
|
|
5
|
+
.PHONY: validate validate-consumer verify-baseline verify-perf
|
|
6
6
|
|
|
7
7
|
validate: ## Invariantes del core: estructura, plantillas, ADR-0, sintaxis, evidencia
|
|
8
8
|
bash -n scripts/compat_check.sh
|
|
@@ -10,6 +10,12 @@ validate: ## Invariantes del core: estructura, plantillas, ADR-0, sintaxis, evid
|
|
|
10
10
|
$(PY) scripts/collect_metrics.py --self-auto
|
|
11
11
|
$(PYTEST) -q
|
|
12
12
|
|
|
13
|
+
verify-baseline: ## Ejecuta el baseline de verificación y escribe docs/verification/{baseline.json,BASELINE.md}
|
|
14
|
+
$(PY) scripts/verification_baseline.py --markdown
|
|
15
|
+
|
|
16
|
+
verify-perf: ## Ejecuta el baseline de rendimiento y escribe docs/verification/{perf.json,PERF.md}
|
|
17
|
+
$(PY) scripts/verification_perf.py --markdown
|
|
18
|
+
|
|
13
19
|
validate-consumer: ## Invariantes de un repo consumidor: make validate-consumer CONSUMER=../mi-repo
|
|
14
20
|
@test -n "$(CONSUMER)" || { echo "uso: make validate-consumer CONSUMER=<ruta>"; exit 2; }
|
|
15
21
|
$(PY) $(CHECK) $(CONSUMER)
|
|
@@ -34,6 +34,12 @@ class Finding(BaseModel):
|
|
|
34
34
|
- **`Finding.match` es un preview truncado**: suficiente para triaje, insuficiente para re-inyectar el secreto.
|
|
35
35
|
- **`detect` es no destructivo**: el scanner se usa antes de decidir qué se envía; `redact` produce la salida
|
|
36
36
|
que sí puede cruzar el límite del prompt.
|
|
37
|
+
- **`phone` exige forma escrita (corregido en v1.1, F2):** prefijo `+`, paréntesis
|
|
38
|
+
o un separador interno. Una tirada de 10 dígitos desnuda (`1725000000`) y los
|
|
39
|
+
últimos dígitos de un UUID se contaban como teléfono; el baseline los medía como
|
|
40
|
+
falsos positivos (2 de 10 negativos duros). El intercambio es explícito: se
|
|
41
|
+
pierde `llama al 3001234567` sin separador, y esa es una decisión medida, no
|
|
42
|
+
accidental. Oráculo: `scripts/verification_baseline.py` (`detectors`).
|
|
37
43
|
|
|
38
44
|
## 3. Perfil y lints (§3.1.1 → ci-pack)
|
|
39
45
|
|
|
@@ -41,8 +41,22 @@ html = render(report) # → docs/metrics/evidence.html
|
|
|
41
41
|
`uv sync --frozen` + replay. Reproduce el patrón que el retrofit #0 de la sem. 6
|
|
42
42
|
copiaba a mano.
|
|
43
43
|
- **`collect` lee fuentes de verdad, no promesas:** manifiestos `core-consumer.yml`
|
|
44
|
-
(reutilización y matriz repo × core), `prompts/` con su `eval` existente (cobertura)
|
|
45
|
-
|
|
44
|
+
(reutilización y matriz repo × core), `prompts/` con su `eval` existente (cobertura),
|
|
45
|
+
los spans de `llm-client` y los cassettes del repo (costo y llamadas). De cada fuente
|
|
46
|
+
que falte, cuenta cero.
|
|
47
|
+
- **Un cero declara su procedencia (F3, v1.1).** La regla de arriba ("cuenta cero") es
|
|
48
|
+
correcta para el *conteo* y falsa para la *interpretación*: la tabla mostraba
|
|
49
|
+
`$0.0000` en las 12 filas y eso mezclaba tres cosas distintas. La página separa ahora
|
|
50
|
+
`llamadas (span)` de `llamadas (cassette)`, publica tokens in/out, y rotula el costo:
|
|
51
|
+
`(spans)`, `(cassette · modelo en tabla de precios)`, `costo desconocido` o
|
|
52
|
+
`sin datos de llamada`. El caso que motiva la cuarta etiqueta: `cost_usd` devuelve 0
|
|
53
|
+
para un modelo que no está en la tabla de precios, así que un modelo de pago sin
|
|
54
|
+
pricedar reportaba $0 y el cap de costo no disparaba. `llm_client.pricing` gana
|
|
55
|
+
`model_price_known()` y `price_key()` para separar "gratis" de "desconocido" y para
|
|
56
|
+
resolver el prefijo de proveedor (`opencode/big-pickle` → `big-pickle`).
|
|
57
|
+
- **Un cassette no es un span.** Aporta `usage` real del proveedor pero no pasó por el
|
|
58
|
+
pipeline del core: no tiene `latency_ms` ni `retry_count`. Por eso van en columnas
|
|
59
|
+
separadas y no se suman en un único "llamadas".
|
|
46
60
|
- **Dependencias hojas:** `llm-dev-client` (solo para el schema de `Span`) y
|
|
47
61
|
`llm-dev-secure-base`. No depende de `test-kit` (el job solo lo *invoca* por CLI).
|
|
48
62
|
|
|
@@ -48,7 +48,11 @@ cliente, si se usa); el `CachedProvider` no toca el span.
|
|
|
48
48
|
- **Los streams existen pero no se cachean:** para un flujo de tokens, cachear el primer
|
|
49
49
|
chunk no sirve; v1 los deja pasar con su token del bucket y cuenta miss.
|
|
50
50
|
- **Poda por expiración:** TTL por entrada; `complete` poda vencidos de paso (sin
|
|
51
|
-
|
|
51
|
+
background thread, sin busy-wait). Desde v1.1.1 (issue #1) la poda es **amortizada**:
|
|
52
|
+
a lo sumo una por ventana de `ttl/2`, porque podar en *cada* llamada hacía el hit
|
|
53
|
+
O(n) en el tamaño del store (medido: 1.8 µs con 1 entrada vs 45 µs con 2 500). Una
|
|
54
|
+
entrada vencida nunca se devuelve —la frescura se comprueba por entrada— pero puede
|
|
55
|
+
quedar en memoria hasta la próxima poda (~1.5×`ttl`).
|
|
52
56
|
|
|
53
57
|
## 3. Qué NO contrata este documento
|
|
54
58
|
|
|
@@ -55,6 +55,23 @@ source = iter_documents("corpus/") # list[Path] determinista
|
|
|
55
55
|
necesite de verdad (D9, `scraper`).
|
|
56
56
|
- **El lector captura, no opina:** tablas como `Table` y también dentro del
|
|
57
57
|
`body` de su sección; el consumidor elige qué pasar al prompt.
|
|
58
|
+
- **Contrato de líneas (corregido en v1.1, F2):** `line_start` es la línea del
|
|
59
|
+
heading y `line_end` la última línea con contenido, de modo que el `body` es
|
|
60
|
+
exactamente `"\n".join(lines[line_start:line_end])` con el relleno exterior
|
|
61
|
+
recortado. El texto del heading vive en `title`, nunca dentro de `body`, y la
|
|
62
|
+
ruta H1-fallback (documento sin H2+) respeta la misma regla.
|
|
63
|
+
- **`line_start == 0` es una señal, no una línea:** la línea 0 no existe en un
|
|
64
|
+
archivo, así que el valor 0 significa "este documento no tiene heading y `body`
|
|
65
|
+
arranca en la línea 1". Un consumidor que renderice el rango debe acotarlo con
|
|
66
|
+
`max(1, line_start)` en vez de imprimir `L0`; `content-ray` lo hace y lo prueba.
|
|
67
|
+
- **Un heading sin cuerpo no es ruido:** se conserva con `body == ""`,
|
|
68
|
+
`body_tokens == 0` y `line_end == line_start`. Antes se descartaba en silencio
|
|
69
|
+
(el `except ValueError: continue` silenciaba además el rango vacío), que es
|
|
70
|
+
pérdida de información sin aviso.
|
|
71
|
+
- **Lo que sigue siendo pérdida, y declarada:** las líneas que no pertenecen a
|
|
72
|
+
ninguna sección (frontmatter, H1, preámbulo antes del primer H2) no aparecen
|
|
73
|
+
en `sections[]`. El baseline mide cuántas son en cada repositorio en vez de
|
|
74
|
+
fingir cobertura total.
|
|
58
75
|
|
|
59
76
|
## 3. Qué NO contrata este documento
|
|
60
77
|
|
|
@@ -75,4 +92,10 @@ source = iter_documents("corpus/") # list[Path] determinista
|
|
|
75
92
|
- [x] `ParseError` con `source` + `line` para JSON inválido y extensiones sin lectura.
|
|
76
93
|
- [x] `approx_tokens` determinista; `iter_documents` determinista y recursivo.
|
|
77
94
|
- [x] Primer consumidor real: `content-ray` (sem. 10) — escanea los `.md` de
|
|
78
|
-
`llm-dev-core`, ventanas por sección y digest LLM validado.
|
|
95
|
+
`llm-dev-core`, ventanas por sección y digest LLM validado.
|
|
96
|
+
- [x] (v1.1) Invariante verificable: `body == lines[line_start:line_end]` en el
|
|
97
|
+
100% de las secciones del corpus real, por las dos rutas.
|
|
98
|
+
Oráculo: `scripts/verification_baseline.py` (`slice_fidelity`).
|
|
99
|
+
- [x] (v1.1) Un heading sin cuerpo sobrevive con rango vacío y `body_tokens == 0`.
|
|
100
|
+
Oráculo: `scripts/verification_baseline.py` (`empty_heading`) y
|
|
101
|
+
`packages/parser-io/tests/test_parser_io.py`.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Contrato mínimo — `diff-engine`
|
|
2
|
+
|
|
3
|
+
- **Fecha:** 2026-11-20
|
|
4
|
+
- **Estado:** aceptada
|
|
5
|
+
- **Origen:** el calendario C1–C18 (§5): `diff-engine` (C12) es la base para comparar
|
|
6
|
+
artefactos de la flota — cassettes de una misma sesión de eval, salidas de prompts
|
|
7
|
+
entre versiones, documentos entre tags. Nació vencida esa deuda: su seed iba en la
|
|
8
|
+
sem. 19 y esa semana pagó la verificación (F0–F4).
|
|
9
|
+
- **Implementada en:** semana 19 (`packages/diff-engine` v0.1.0, dentro de `llm-dev-core`
|
|
10
|
+
v1.2.0; primer consumidor: `cassette-diff`)
|
|
11
|
+
|
|
12
|
+
Comparar dos textos con los ojos encuentra lo que uno espera encontrar. La flota necesita
|
|
13
|
+
comparar artefactos que nadie mira línea a línea: dos grabaciones del mismo prompt, la
|
|
14
|
+
salida de un prompt antes y después de editarlo. Esa comparación tiene que ser
|
|
15
|
+
**determinista** y tiene que saber **qué no comparar**: un `timestamp` distinto no es deriva.
|
|
16
|
+
|
|
17
|
+
## 1. API conceptual
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from diff_engine import diff_records, diff_text, text_similarity, VOLATILE_FIELDS
|
|
21
|
+
|
|
22
|
+
report = diff_records(llamada_a, llamada_b) # campos, hunks, veredicto
|
|
23
|
+
report.igual # False si algún campo no volátil cambió
|
|
24
|
+
report.similitud_texto # [0, 1] sobre el campo de respuesta
|
|
25
|
+
report.hunks # bloques cambiada/agregada/eliminada con líneas
|
|
26
|
+
report.volatiles_ignorados # lo que NO se comparó, a la vista
|
|
27
|
+
|
|
28
|
+
hunks = diff_text("antes…", "después…") # hunks línea a línea
|
|
29
|
+
ratio = text_similarity("a", "b") # [0, 1], determinista
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## 2. Reglas
|
|
33
|
+
|
|
34
|
+
- **La hoja no cambia:** `diff-engine` no depende de ningún módulo del core (stdlib +
|
|
35
|
+
`pydantic`), como `bot-base`. El que compara no llama modelos; el consumidor compone.
|
|
36
|
+
- **Determinismo (D4):** `difflib` puro, sin relojes, sin aleatoriedad, sin red: mismas
|
|
37
|
+
entradas, mismo diff. Dos corridas devuelven el mismo reporte byte a byte.
|
|
38
|
+
- **Volátiles declarados, no adivinados:** `VOLATILE_FIELDS` (timestamps, ids, latencias)
|
|
39
|
+
se ignoran por defecto y **se listan en el reporte**: ignorar en silencio es mentir con
|
|
40
|
+
estadística. Quien compare otra cosa, pasa los suyos (`volatiles=`).
|
|
41
|
+
- **Campos de texto por similitud, el resto por igualdad:** un texto que cambió de
|
|
42
|
+
palabra no es un booleano; un `usage` que cambió de número, sí.
|
|
43
|
+
- **Hunks con líneas, no parches:** el consumidor muestra lo que cambió; aplicar el
|
|
44
|
+
cambio es trabajo de un `patcher` que nadie ha pedido.
|
|
45
|
+
|
|
46
|
+
## 3. Qué NO contrata este documento
|
|
47
|
+
|
|
48
|
+
- **Similitud semántica** (embeddings, significado): eso es `vector-core` (C11), con su
|
|
49
|
+
propio ADR cuando se siembre. Aquí "parecido" es textual, medible y reproducible.
|
|
50
|
+
- **Diff de tres vías o merge**: no hay consumidor que lo pida (D1).
|
|
51
|
+
- **Formatos binarios o diff estructurado de AST**: texto y JSON plano; lo demás cuando
|
|
52
|
+
dos consumidores lo necesiten (D12).
|
|
53
|
+
|
|
54
|
+
## 4. Criterio de aceptación del contrato (semana 19)
|
|
55
|
+
|
|
56
|
+
- [x] `diff_records` campo a campo con volátiles ignorados y listados.
|
|
57
|
+
- [x] `diff_text` en hunks `cambiada/agregada/eliminada` con líneas y posiciones.
|
|
58
|
+
- [x] `text_similarity` en [0, 1], determinista.
|
|
59
|
+
- [x] Primer consumidor real: `cassette-diff` (sem. 19) — deriva del modelo entre dos
|
|
60
|
+
grabaciones del mismo prompt, narrada con LLM validado.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Contrato mínimo — `agent-loop`
|
|
2
|
+
|
|
3
|
+
- **Fecha:** 2026-11-20
|
|
4
|
+
- **Estado:** aceptada
|
|
5
|
+
- **Origen:** el calendario C1–C18 (§5): `agent-loop` (C13) es la base del agente con
|
|
6
|
+
herramientas del reto. No es un chatbot ni un orquestador de gráficos: es **el loop
|
|
7
|
+
mínimo con puerta humana** — proponer, confirmar, ejecutar, registrar.
|
|
8
|
+
- **Implementada en:** semana 21 (`packages/agent-loop` v0.1.0, dentro de `llm-dev-core`
|
|
9
|
+
v1.3.0; primer consumidor: `checklist-walker`)
|
|
10
|
+
|
|
11
|
+
Un "agente" sin confirmación es un `rm -rf` con buena retórica. Lo que la flota necesita
|
|
12
|
+
antes de autonomía es el esqueleto honesto: un loop donde cada acción con efecto pasa por
|
|
13
|
+
una puerta explícita, donde el error de una herramienta no mata la corrida, y donde todo
|
|
14
|
+
queda en un trace auditable.
|
|
15
|
+
|
|
16
|
+
## 1. API conceptual
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
from agent_loop import Action, ToolRegistry, run_agent
|
|
20
|
+
|
|
21
|
+
registry = ToolRegistry()
|
|
22
|
+
registry.register("leer", "lee un archivo", fn) # (nombre, descripción, callable)
|
|
23
|
+
|
|
24
|
+
trace = run_agent(
|
|
25
|
+
"verificar el repo",
|
|
26
|
+
registry=registry,
|
|
27
|
+
brain=mi_cerebro, # dict(vista) -> Action: la próxima acción
|
|
28
|
+
confirm=lambda a: False, # puerta humana antes de ejecutar (None = sin puerta)
|
|
29
|
+
max_steps=8, # presupuesto de pasos propuestos
|
|
30
|
+
)
|
|
31
|
+
trace.paro # "done" | "rechazado" | "presupuesto"
|
|
32
|
+
trace.steps # [{n, accion, estado, salida|detalle}] — la corrida completa
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 2. Reglas
|
|
36
|
+
|
|
37
|
+
- **La hoja no cambia y el runner es agnóstico:** `agent-loop` no depende de ningún
|
|
38
|
+
módulo del core (solo `pydantic`) ni llama a ningún modelo. El "cerebro" es un
|
|
39
|
+
callable inyectado — un cierre sobre `LlmClient` en producción, un guion en los
|
|
40
|
+
tests. Determinismo por construcción (D4), como `bot-base`.
|
|
41
|
+
- **Confirmación explícita antes del efecto:** `confirm(action) -> bool` corre antes
|
|
42
|
+
de ejecutar la herramienta; un `False` termina con `paro="rechazado"` — el agente
|
|
43
|
+
no insiste ni reintenta la puerta. Sin `confirm`, el consumidor decidió no poner
|
|
44
|
+
puerta y lo firma.
|
|
45
|
+
- **El error de una herramienta es del paso, no del loop:** el paso queda `error`
|
|
46
|
+
con su detalle y el cerebro decide la siguiente acción (cambiar de ruta o terminar).
|
|
47
|
+
Nada se corta en silencio (§5.1).
|
|
48
|
+
- **Presupuesto de pasos obligatorio:** sin `max_steps` el loop podría vivir para
|
|
49
|
+
siempre; agotado el presupuesto, `paro="presupuesto"` — visible, no un timeout.
|
|
50
|
+
- **El trace es la evidencia:** cada paso lleva acción propuesta (con su razón),
|
|
51
|
+
estado y salida acotada. Quien audita no necesita volver a correr el agente.
|
|
52
|
+
|
|
53
|
+
## 3. Qué NO contrata este documento
|
|
54
|
+
|
|
55
|
+
- **El cerebro:** cómo el LLM elige herramientas es problema del consumidor (componer
|
|
56
|
+
`llm-client` + `schema-validate`); aquí solo se exige que devuelva `Action`.
|
|
57
|
+
- **Memoria entre corridas ni planificación multi-agente:** un loop, un goal, un trace.
|
|
58
|
+
- **Efectos compensables (rollback):** la puerta está antes del efecto; deshacer no
|
|
59
|
+
es de esta capa.
|
|
60
|
+
- **Paralelismo de herramientas:** pasos en serie; lo demás cuando dos consumidores
|
|
61
|
+
lo necesiten (D12).
|
|
62
|
+
|
|
63
|
+
## 4. Criterio de aceptación del contrato (semana 21)
|
|
64
|
+
|
|
65
|
+
- [x] `ToolRegistry` con spec visible para el cerebro (nombre + descripción, nunca la
|
|
66
|
+
función) y error visible en duplicadas/desconocidas.
|
|
67
|
+
- [x] `run_agent` con cerebro inyectado, confirmación, presupuesto y trace completo.
|
|
68
|
+
- [x] Error de herramienta no mata el loop; rechazo termina sin insistir.
|
|
69
|
+
- [x] Primer consumidor real: `checklist-walker` (sem. 21) — camina un checklist con
|
|
70
|
+
herramientas de lectura sobre un repo real y reporta con LLM validado.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<!doctype html><html lang="es"><head><meta charset="utf-8"><title>llm-dev-core · página de evidencia</title><style>body{font:14px/1.5 -apple-system,sans-serif;margin:2rem}table{border-collapse:collapse;width:100%}th,td{border:1px solid #ddd;padding:6px 10px;text-align:left}th{background:#f4f4f4}.ok{color:#0a7b0a;font-weight:700}.warn{color:#a15c00;font-weight:700}small{color:#666}</style></head><body><h1>Página de evidencia — llm-dev-core</h1><p>0 consumidores · 0 prompts (<span class="ok">0 con dataset</span>) · 0 llamadas con span guardado · 0 llamadas grabadas en cassettes · 0 tokens in / 0 tokens out · 0/0 en reutilización ≥ 70%.</p><table><thead><tr><th>repo</th><th>sem</th><th>core</th><th>reutilización</th><th>módulos reutilizados</th><th>evals</th><th>llamadas (span)</th><th>llamadas (cassette)</th><th>tokens in/out</th><th>costo</th></tr></thead><tbody></tbody></table><p><small>Una llamada con span es una ejecución instrumentada por `llm-client`. Una llamada en cassette es una grabación de proveedor: trae <code>usage</code> real, pero no pasó por el pipeline del core, así que no tiene <code>latency_ms</code> ni <code>retry_count</code>. El costo solo se declara cuando el modelo está en la tabla de precios; si no, se escribe "costo desconocido" en vez de 0.</small></p></body></html>
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Baseline de verificación (F0-F2.1)
|
|
2
|
+
|
|
3
|
+
Generado por `scripts/verification_baseline.py` el 2026-11-20.
|
|
4
|
+
Artefacto de datos: `docs/verification/baseline.json` (se escribe en cada ejecución).
|
|
5
|
+
|
|
6
|
+
Cada fila cita el archivo y la línea del contrato que mide, el tipo de esa cláusula, el
|
|
7
|
+
oráculo que produce el número y la acción que se abre si el veredicto no es `TRUE`.
|
|
8
|
+
Ninguna cifra de este documento está escrita a mano: todas salen de la ejecución anterior.
|
|
9
|
+
|
|
10
|
+
El tipo lo decide `git show v1.0.0:<archivo>`, no el autor: `PREEXISTENTE` significa que
|
|
11
|
+
el texto ya estaba en el tag, `DECISION v1.1` que lo escribió este trabajo, y
|
|
12
|
+
`CRITERIO DE PROYECTO` que el umbral viene de `docs/verification/METODOLOGIA.md`.
|
|
13
|
+
|
|
14
|
+
| medición | tipo de cláusula | ancla | veredicto | evidencia medida | acción |
|
|
15
|
+
| --- | --- | --- | --- | --- | --- |
|
|
16
|
+
| slice_fidelity | DECISION v1.1 | `docs/decisions/0009-parser-io-contract.md:58` | TRUE | 250/250 secciones (100.0%) cumplen body == lines[line_start:line_end]; 620 líneas con contexto fuera de toda sección; 41 H1 y 0 H2+ ausentes del resultado | — |
|
|
17
|
+
| idempotence | PREEXISTENTE | `docs/decisions/0009-parser-io-contract.md:50` | TRUE | 58/58 documentos idénticos en dos parses del mismo archivo | — |
|
|
18
|
+
| empty_heading | DECISION v1.1 | `docs/decisions/0009-parser-io-contract.md:67` | TRUE | excepción=None; secciones devueltas=['Sección vacía', 'Con contenido']; sección vacía conservada=True, rango coherente=True | — |
|
|
19
|
+
| schema_enumeration | PREEXISTENTE | `docs/decisions/0002-schema-validate-contract.md:37` | TRUE | 14/14 entradas clasificadas como espera ADR-2 §2 | — |
|
|
20
|
+
| detectors | DECISION v1.1 | `docs/decisions/0003-secure-base-contract.md:22`, `docs/decisions/0003-secure-base-contract.md:37` | TRUE | 9/9 positivos; 0 hallazgos en 8692 líneas de producción; 0/10 negativos duros marcados | — |
|
|
21
|
+
| time_invariants | PREEXISTENTE | `docs/decisions/0007-cache-ratelimit-contract.md:21`, `docs/decisions/0007-cache-ratelimit-contract.md:50`, `docs/decisions/0008-bot-base-contract.md:72` | TRUE | TTL respetado=True; bucket 2.0→2.0; run_tasks 1ª=ok, 2ª=skipped, tras 90.000 s=ok | — |
|
|
22
|
+
| span_contract | PREEXISTENTE | `docs/decisions/0001-llm-client-contract.md:58` | TRUE | 20 campos en código contra 20 enumerados en ADR-1 §2 (línea 58); faltan=[], sobran=[] | — |
|
|
23
|
+
| evidence_self_audit | CRITERIO DE PROYECTO | `docs/verification/METODOLOGIA.md:52`, `docs/decisions/0006-ci-pack-contract.md:47` | TRUE | 19 filas, 19 con datos de llamada: 61 en cassettes + 0 con span; 519143 tokens in / 14570 out; filas con costo desconocido=0 | — |
|
|
24
|
+
| docs_claims | CRITERIO DE PROYECTO | `docs/verification/METODOLOGIA.md:29`, `docs/verification/METODOLOGIA.md:35` | TRUE | 19 cifras de contrato en 19 READMEs, 19 coinciden con su oráculo y 0 son falsas; el resto de cifras son {'identificador': 44, 'cronologia': 43, 'contrato': 19, 'http': 15, 'puerto': 14, 'referencia': 12, 'fecha': 6} y no son claims | — |
|
|
25
|
+
|
|
26
|
+
Totales: 9 `TRUE`, 0 `PARCIAL`, 0 `FALSE`.
|
|
27
|
+
|
|
28
|
+
## Historial de cláusulas (autorreferencia declarada)
|
|
29
|
+
|
|
30
|
+
En **F0** este informe declaraba sus propias cláusulas dentro del script. Eso hace
|
|
31
|
+
imposible distinguir "el código cumple el contrato" de "el código cumple lo que yo
|
|
32
|
+
acabo de escribir". Dos consecuencias, registradas aquí para que no se pierdan:
|
|
33
|
+
|
|
34
|
+
- El `FALSE` de F0 en `empty_heading` se apoyaba en una cláusula que **inventé**
|
|
35
|
+
("una sección vacía produce `ParseError` tipado"). Nada en ADR-9 pedía eso. El
|
|
36
|
+
defecto de fondo —que la sección desapareciera en silencio— sí era verificable sin
|
|
37
|
+
esa cláusula; la etiqueta correcta en F0 habría sido "no documentado", no `FALSE`.
|
|
38
|
+
El arreglo de F2 (conservar la sección vacía con rango vacío) es una **decisión de
|
|
39
|
+
v1.1**, y por eso esa fila figura como tal.
|
|
40
|
+
- `slice_fidelity` y `detectors` miden invariantes que también se escribieron en v1.1.
|
|
41
|
+
Verificarlos demuestra que la decisión está implementada, no que el core antiguo
|
|
42
|
+
cumplía algo. La cita que sí era preexistente en `detectors` es la lista de 9 tipos
|
|
43
|
+
(ADR-3 línea 22).
|
|
44
|
+
|
|
45
|
+
Las anclas se verifican en `scripts/verification_clauses.py` y la suite falla si una
|
|
46
|
+
cita deja de existir o si una cláusula `PREEXISTENTE` no está en el tag.
|
|
47
|
+
|
|
48
|
+
## Cómo reproducir
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
make verify-baseline
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Equivale a `uv run python scripts/verification_baseline.py --markdown`.
|
|
55
|
+
|
|
56
|
+
El corpus excluye su propia salida (`docs/verification/`), de modo que dos corridas seguidas
|
|
57
|
+
producen el mismo JSON salvo la marca de tiempo. El corpus **sí** incluye el código del
|
|
58
|
+
repositorio, así que el baseline es una foto del árbol: si cambia el código, hay que
|
|
59
|
+
regenerarlo. `tests/test_verification_baseline.py` falla si el JSON commiteado no coincide
|
|
60
|
+
con una medición fresca, así que esa desincronización no puede pasar inadvertida.
|
|
61
|
+
|
|
62
|
+
## Qué NO prueba este baseline
|
|
63
|
+
|
|
64
|
+
- `schema_enumeration` clasifica 14 entradas escritas a mano para cubrir las cláusulas de ADR-2 §2;
|
|
65
|
+
no es una enumeración exhaustiva de JSON malformado.
|
|
66
|
+
- `detectors` mide 9 positivos y 10 negativos duros. No hay corpus de terceros, así que la
|
|
67
|
+
precisión real queda acotada, no demostrada.
|
|
68
|
+
- Ninguna cifra de este documento mide utilidad, calidad o utilidad de salida LLM: eso queda
|
|
69
|
+
fuera del alcance objetivo y solo puede afirmarse con datos de ejecución guardados.
|