evals-promptdb 1.2.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.
Files changed (36) hide show
  1. evals_promptdb-1.2.0/CHANGELOG.md +43 -0
  2. evals_promptdb-1.2.0/LICENSE +21 -0
  3. evals_promptdb-1.2.0/MANIFEST.in +6 -0
  4. evals_promptdb-1.2.0/PKG-INFO +301 -0
  5. evals_promptdb-1.2.0/README.es.md +271 -0
  6. evals_promptdb-1.2.0/README.md +271 -0
  7. evals_promptdb-1.2.0/assets/evals-promptdb.png +0 -0
  8. evals_promptdb-1.2.0/evals_promptdb.egg-info/PKG-INFO +301 -0
  9. evals_promptdb-1.2.0/evals_promptdb.egg-info/SOURCES.txt +34 -0
  10. evals_promptdb-1.2.0/evals_promptdb.egg-info/dependency_links.txt +1 -0
  11. evals_promptdb-1.2.0/evals_promptdb.egg-info/entry_points.txt +2 -0
  12. evals_promptdb-1.2.0/evals_promptdb.egg-info/top_level.txt +1 -0
  13. evals_promptdb-1.2.0/examples/evaluate.py +179 -0
  14. evals_promptdb-1.2.0/promptdb/__init__.py +27 -0
  15. evals_promptdb-1.2.0/promptdb/__main__.py +3 -0
  16. evals_promptdb-1.2.0/promptdb/_snapshots.py +163 -0
  17. evals_promptdb-1.2.0/promptdb/_values.py +102 -0
  18. evals_promptdb-1.2.0/promptdb/_version.py +1 -0
  19. evals_promptdb-1.2.0/promptdb/cli.py +352 -0
  20. evals_promptdb-1.2.0/promptdb/database.py +664 -0
  21. evals_promptdb-1.2.0/promptdb/py.typed +1 -0
  22. evals_promptdb-1.2.0/promptdb/records.py +128 -0
  23. evals_promptdb-1.2.0/promptdb/schema.py +73 -0
  24. evals_promptdb-1.2.0/promptdb/scorers.py +44 -0
  25. evals_promptdb-1.2.0/pyproject.toml +49 -0
  26. evals_promptdb-1.2.0/setup.cfg +4 -0
  27. evals_promptdb-1.2.0/tests/fixtures/schema-v1.sql +55 -0
  28. evals_promptdb-1.2.0/tests/test_async.py +83 -0
  29. evals_promptdb-1.2.0/tests/test_chat.py +68 -0
  30. evals_promptdb-1.2.0/tests/test_cli.py +195 -0
  31. evals_promptdb-1.2.0/tests/test_database.py +249 -0
  32. evals_promptdb-1.2.0/tests/test_provider_examples.py +102 -0
  33. evals_promptdb-1.2.0/tests/test_quality.py +97 -0
  34. evals_promptdb-1.2.0/tests/test_scorers.py +30 -0
  35. evals_promptdb-1.2.0/tests/test_snapshots.py +96 -0
  36. evals_promptdb-1.2.0/tests/test_test_cases.py +59 -0
@@ -0,0 +1,43 @@
1
+ # Historial de cambios
2
+
3
+ ## 1.2.0
4
+
5
+ - Prompts de chat con mensajes de texto ordenados, variables por mensaje y ejemplos para Ollama, OpenAI, Anthropic y servidores compatibles con Chat Completions.
6
+ - Evaluaciones síncronas y asíncronas con selección por etiqueta y subconjuntos de casos. Las esperas del proveedor quedan fuera de las transacciones SQLite.
7
+ - Archivado, reactivación y reemplazo de casos con historial de evaluaciones. La cobertura usa los casos activos por defecto.
8
+ - Evaluadores de texto y JSON estructural. La CLI acepta salidas de otro proceso por archivo o stdin.
9
+ - Modo de solo lectura, comprobación de integridad, exportación a archivo y E/S UTF-8 en la CLI.
10
+ - Migraciones transaccionales al esquema SQLite 4. El formato de snapshot 4 acepta importaciones de los formatos anteriores.
11
+ - Tipos incluidos en el wheel y matriz de CI ampliada para CPython 3.15 y PyPy 3.11.
12
+
13
+ ## 1.1.0
14
+
15
+ - Puntuaciones por caso, cobertura y comparación sobre los casos compartidos por la versión base y la candidata.
16
+ - `compare --min-coverage` y `compare --max-regression` para controlar cobertura y regresión en CI.
17
+ - Identificadores de corrida en `run_tests()` y `add_eval()`, con filtro `run_id` en la API y `--run-id` en la CLI.
18
+ - Migración transaccional al esquema SQLite 2. Los snapshots JSON de formato 2 conservan los identificadores de corrida y pueden importar el formato 1.
19
+ - Ejemplo ejecutable con Ollama, OpenAI, Anthropic y un generador determinista sin conexión.
20
+
21
+ ## 1.0.0
22
+
23
+ - La distribución pasa a llamarse `evals-promptdb`. El módulo y el comando se llaman `promptdb`.
24
+ - `export_json()` y `import_json()` guardan y restauran un snapshot JSON reproducible con los identificadores, las fechas y la secuencia de versiones. La CLI ofrece `export` e `import`.
25
+ - `run_tests()` ejecuta los casos de una versión con un generador y un evaluador configurables. Los resultados se guardan en una sola transacción.
26
+ - `compare --min-score` devuelve el código 3 si la última versión comparada queda por debajo del umbral o carece de evaluaciones que coincidan con los filtros.
27
+ - Documentación completa en inglés y español y nuevo icono.
28
+ - Compatibilidad de lectura y escritura con los archivos SQLite de 0.1.0 y 0.2.0.
29
+
30
+ ## 0.2.0
31
+
32
+ - Copias consistentes de SQLite con `PromptDB.backup()` y `promptdb backup`.
33
+ - `promptdb tag` permite reemplazar o quitar las etiquetas de una versión.
34
+ - `promptdb eval --created-at` acepta la fecha de una evaluación existente.
35
+ - Los comandos de la CLI requieren una base existente, excepto `save`, que puede crearla.
36
+ - Las lecturas pueden abrir una base mientras otro proceso tiene una escritura reservada. La espera ante bloqueos se puede configurar desde Python.
37
+ - La distribución pasa a llamarse `promptdb-local`. El módulo y el comando se llaman `promptdb`. Se pueden abrir las bases creadas con 0.1.0.
38
+ - Pruebas de persistencia, concurrencia, recuperación ante fallos, evaluaciones y CLI.
39
+
40
+ ## 0.1.0
41
+
42
+ - Versionado de plantillas SQLite, variables, etiquetas, casos de prueba y evaluaciones.
43
+ - Comparación de versiones y rollback por etiqueta desde Python y la CLI.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PromptDB contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,6 @@
1
+ include CHANGELOG.md
2
+ include README.es.md
3
+ include assets/evals-promptdb.png
4
+ include examples/*.py
5
+ include tests/test_*.py
6
+ include tests/fixtures/schema-v1.sql
@@ -0,0 +1,301 @@
1
+ Metadata-Version: 2.4
2
+ Name: evals-promptdb
3
+ Version: 1.2.0
4
+ Summary: A local, embedded SQLite database for versioned LLM prompts
5
+ License-Expression: MIT
6
+ Project-URL: Repository, https://github.com/Arcynox/EvalsPromptDB
7
+ Project-URL: Documentation, https://github.com/Arcynox/EvalsPromptDB#readme
8
+ Project-URL: Issues, https://github.com/Arcynox/EvalsPromptDB/issues
9
+ Keywords: llm,prompts,versioning,evaluation,sqlite
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Programming Language :: Python :: Implementation :: CPython
22
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
23
+ Classifier: Topic :: Database
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Dynamic: license-file
30
+
31
+ <div align="center">
32
+ <img src="assets/evals-promptdb.png" width="128" height="128" alt="Evals PromptDB icon">
33
+ <h1>Evals PromptDB</h1>
34
+ <p><strong>Local SQLite storage for versioned LLM prompts and evaluations.</strong></p>
35
+ <p>
36
+ <a href="https://github.com/Arcynox/EvalsPromptDB/actions/workflows/ci.yml"><img src="https://github.com/Arcynox/EvalsPromptDB/actions/workflows/ci.yml/badge.svg" alt="GitHub Actions CI status"></a>
37
+ <a href="#install"><img src="https://img.shields.io/badge/Python-3.10%2B-6d4aff" alt="Python 3.10 and later"></a>
38
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-27896d" alt="MIT license"></a>
39
+ </p>
40
+ <p>
41
+ <a href="README.es.md">Español</a> · <a href="#install">Install</a> · <a href="#quickstart-in-python">Python quickstart</a> · <a href="#quickstart-in-the-terminal">CLI quickstart</a> · <a href="#provider-examples">Providers</a>
42
+ </p>
43
+ </div>
44
+
45
+ Keep templates, test cases, model outputs, and scores in one `.db` file. Use the Python API in your application or the CLI in scripts and CI. The core uses the Python standard library.
46
+
47
+ ## Prompt workflow
48
+
49
+ | Step | What you can do |
50
+ | --- | --- |
51
+ | **Version** | Save immutable templates and select the active version by tag. |
52
+ | **Evaluate** | Run the same cases across versions with a generator and scorer you supply. |
53
+ | **Compare and promote** | Inspect diffs, scores, and coverage. Gate promotion in CI and roll back by moving the tag. |
54
+ | **Share** | Track deterministic JSON in Git or transfer a consistent SQLite backup. |
55
+
56
+ ## Install
57
+
58
+ Use Python 3.10 or later. Install from this checkout.
59
+
60
+ ```bash
61
+ python -m pip install .
62
+ promptdb --version
63
+ ```
64
+
65
+ The distribution is named `evals-promptdb`. Import `PromptDB` from `promptdb`, and run `promptdb` or `python -m promptdb`. You can run `python -m promptdb` from the checkout without installing it.
66
+
67
+ If you installed PromptDB 0.1.0 or 0.2.0 from this project, remove the old distribution (`promptdb` or `promptdb-local`, respectively) from that environment before installing `evals-promptdb`. Opening an older SQLite file with a writable connection migrates it in a single transaction. Use the upgraded package to open migrated files.
68
+
69
+ ## Quickstart in Python
70
+
71
+ Run this in a directory without a `prompts.db` file. The demo functions stand in for model calls so the example runs offline.
72
+
73
+ ```python
74
+ from promptdb import PromptDB
75
+
76
+ with PromptDB("prompts.db") as db:
77
+ v1 = db.save(
78
+ "country",
79
+ "Give the country containing {{city}}.",
80
+ tags=["production"],
81
+ metadata={"team": "examples"},
82
+ )
83
+ v2 = db.save(
84
+ "country",
85
+ "Return only the name of the country containing {{city}}.",
86
+ tags=["experiment"],
87
+ )
88
+ case = db.add_test("country", input={"city": "Madrid"}, expected="Spain")
89
+
90
+ current = db.get("country", tag="production")
91
+ print(current.render(case.input))
92
+
93
+ db.run_tests("country", version=v1.version, model="demo",
94
+ generate=lambda text: "Madrid is in Spain.", run_id="quickstart")
95
+ db.run_tests("country", version=v2.version, model="demo",
96
+ generate=lambda text: "Spain", run_id="quickstart")
97
+
98
+ report = db.compare("country", [v1.version, v2.version], model="demo", run_id="quickstart")
99
+ print(report.versions[1].diff)
100
+ print(report.versions[1].coverage) # 1.0
101
+ print(report.best.prompt.version) # 2
102
+
103
+ db.promote("country", v2.version, tag="production")
104
+ db.promote("country", v1.version, tag="production") # Roll back
105
+ ```
106
+
107
+ The same case applies to both versions. By default, `run_tests()` scores text by exact match after trimming surrounding whitespace. A custom `scorer(output, expected)` can return any numeric score from 0 to 1 and is required for non-text expectations.
108
+
109
+ ## Chat prompts
110
+
111
+ Store ordered text messages when the model needs distinct instruction and conversation roles. Variables work in every message. The supported roles are `system`, `developer`, `user`, and `assistant`.
112
+
113
+ ```python
114
+ from promptdb import PromptDB
115
+
116
+ with PromptDB(":memory:") as db:
117
+ prompt = db.save("translate", messages=[
118
+ {"role": "system", "content": "Translate the user's text to {{language}}."},
119
+ {"role": "user", "content": "{{text}}"},
120
+ ])
121
+ inputs = {"language": "Spanish", "text": "Good morning"}
122
+ messages = prompt.render_messages(inputs)
123
+ db.add_test("translate", input=inputs, expected="Buenos días")
124
+ db.run_tests("translate", model="demo", generate_messages=lambda conversation: "Buenos días")
125
+ ```
126
+
127
+ `Prompt.kind` distinguishes `text` and `chat`. `render_messages()` also accepts text prompts and wraps their rendered text in a single user message. `render()` returns JSON text for chat prompts. Use `generate_messages` to pass the rendered messages directly to your model client.
128
+
129
+ ```bash
130
+ promptdb --db chat.db save translate --messages - <<'JSON'
131
+ [{"role":"system","content":"Translate to {{language}}."},{"role":"user","content":"{{text}}"}]
132
+ JSON
133
+ promptdb --db chat.db get translate --input '{"language":"Spanish","text":"Good morning"}'
134
+ ```
135
+
136
+ ## Quickstart in the terminal
137
+
138
+ These commands use a fresh database named `cli.db`.
139
+
140
+ ```bash
141
+ promptdb --db cli.db save country --template 'Give the country containing {{city}}.' --tag production
142
+ promptdb --db cli.db save country --template 'Return only the country name for {{city}}.' --tag experiment
143
+ promptdb --db cli.db get country --tag production --input '{"city":"Madrid"}'
144
+ promptdb --db cli.db add-test country --input '{"city":"Madrid"}' --expected '"Spain"'
145
+ promptdb --db cli.db eval country --version 1 --model demo --run-id demo-1 --test-id 1 --score 0.83
146
+ promptdb --db cli.db eval country --version 2 --model demo --run-id demo-1 --test-id 1 --score 0.87
147
+ promptdb --db cli.db compare country 1 2 --model demo --run-id demo-1 --min-score 0.85 --min-coverage 1 --max-regression 0.02
148
+ promptdb --db cli.db promote country 2 --tag production
149
+ ```
150
+
151
+ <details>
152
+ <summary>Example comparison output</summary>
153
+
154
+ ```text
155
+ Version Variables Added Removed Evals Avg score Cases Case avg Paired delta
156
+ 1 city - - 1 0.830 1/1 0.830 -
157
+ 2 city - - 1 0.870 1/1 0.870 +0.040 (1)
158
+ ```
159
+
160
+ </details>
161
+
162
+ Use `save --from-file template.txt` for a multiline UTF-8 template and `--from-file -` for standard input. Use `get --json` for a full record, `get --input` for a rendered template, and `compare --json` for a machine-readable comparison. For the full command list, run `promptdb --help`.
163
+
164
+ ### Quality gates in CI
165
+
166
+ The last version in the comparison is the candidate. The first is the baseline. Pass the same `--model` and `--run-id` used when recording the scores so the gate reads one model and one run.
167
+
168
+ | Flag | Condition for passing |
169
+ | --- | --- |
170
+ | `--min-score 0.85` | The candidate meets the score threshold. With a coverage or regression gate, each scored case has equal weight and only scores linked to a case count. On its own, `--min-score` uses the average of all matching evaluation rows. |
171
+ | `--min-coverage 1` | The candidate has scores for 100% of eligible cases. Without `--test-id`, all saved cases for the prompt are eligible. Repeated scores on one case count once toward coverage. |
172
+ | `--max-regression 0.02` | The candidate's case average drops by at most 0.02 against the baseline on their shared cases. Shared coverage must reach `--min-coverage`, or 100% if that flag is omitted. |
173
+
174
+ A failed gate returns status `3`, including when required scores or cases are missing. A passing result returns `0`. Operational errors return `1`, and command-line syntax errors return `2`. The JSON report includes `case_scores`, `coverage`, `case_average_score`, and `paired` for each version, alongside the original row average.
175
+
176
+ ## Python API
177
+
178
+ | Operation | Behavior |
179
+ | --- | --- |
180
+ | `save(name, template, ...)` | Creates a version of a text prompt or accepts `messages=` for chat. Also accepts `version`, `variables`, `model`, `temperature`, `metadata`, and `tags`. |
181
+ | `get(name, version="latest", tag=None)` | Returns the highest matching version. Passing a number and a tag requires both to match. Raises `KeyError` when there is no match. |
182
+ | `Prompt.render(values)` | Replaces detected placeholders in one pass. Extra inputs are allowed. A missing input raises `KeyError`. |
183
+ | `list(tags=())` and `history(name)` | List versions. Filtering by tags requires every requested tag. History orders versions from oldest to newest. |
184
+ | `set_tags(name, version, tags)` | Replaces tags on one version. The CLI equivalent is `tag`. |
185
+ | `promote(name, version, tag="produccion")` | Moves a tag to exactly one version of that prompt in a single transaction. |
186
+ | `add_test(name, input=..., expected=...)` and `list_tests(name)` | Store cases shared by all versions of a prompt and list the active cases. |
187
+ | `get_test(name, test_id)` | Read a case by ID, including an archived case. |
188
+ | `set_test_archived(name, test_id, archived=True)` and `replace_test(...)` | Manage the active suite while keeping the previous case and its evaluations available. |
189
+ | `add_eval(name, version=..., score=..., model=..., ...)` | Records a score and optionally `test_id`, `run_id`, `output`, `metadata`, and an existing `created_at`. |
190
+ | `run_tests(name, model=..., generate=..., ...)` | Renders active cases, calls the generator, and stores the scored results in one transaction. Select a version or tag and optionally pass `test_ids` to run a subset. |
191
+ | `await arun_tests(name, model=..., generate=..., ...)` | Awaits a text or message generator and supports a synchronous or asynchronous scorer. |
192
+ | `compare(name, versions=None, ...)` and `list_evals(name, ...)` | Read stored evaluations with filters for run ID, model, case, and date. |
193
+ | `delete(name, version)` | Removes one version, its tags, and its evaluations. Associated test cases remain attached to the prompt name. |
194
+
195
+ Placeholder names such as `{{city}}` and `{{ city }}` are detected in first-use order. If you pass `variables` explicitly, use the same set as in the template. Version numbers increase per name, including after deletion. Templates and model settings are immutable once saved. Use a new version for edits.
196
+
197
+ Pass an aware `datetime` for `created_at`, `since`, and `until`. The CLI accepts ISO 8601 timestamps with offsets, such as `2026-11-12T10:00:00-03:00`. Time windows include `since` and exclude `until`. The comparison uses the first requested version as the base of the diff. `report.best` uses the highest `average_score` across matching rows and breaks ties in comparison order. Versions without matching runs have an average of `None`. Compare the same model and a consistent set of cases when using a score as a gate.
198
+
199
+ A batch starts from the prompt and cases visible at the beginning of the run. Model calls and scoring happen outside the SQLite transaction. If rendering, generation, scoring, or persistence fails, the batch leaves no partial results. `run_tests()` assigns an ID to the batch by default. Pass the same `run_id` to the baseline and candidate when evaluating them together.
200
+
201
+ Use `arun_tests()` with an async client in an event loop. It keeps SQLite transactions out of provider `await` calls. Both runners accept `tag` to select a deployed version and `test_ids` to run selected active cases in the requested order. A comparison measures coverage against the cases eligible for that comparison.
202
+
203
+ ### Maintaining test cases
204
+
205
+ Use `archive-test` to retire a case or `restore-test` to make it active again. Use `replace-test NAME ID --input ... --expected ...` to archive the old case and create a new case with its own ID in one transaction. `get-test` and `evals` still show the original case and scores. By default, `run_tests`, `tests`, and `compare` use active cases. Pass `include_archived=True` to `list_tests()` or `compare()`, or `--include-archived` to `tests` or `compare`, to include archived cases in an audit.
206
+
207
+ ### Scoring structured outputs
208
+
209
+ Use `from promptdb.scorers import json_match` and pass `scorer=json_match` to `run_tests()` for a JSON expectation. Field order and insignificant whitespace are ignored. Array order and the difference between numbers and booleans matter. Malformed JSON receives a zero score and its output stays in the evaluation record.
210
+
211
+ To score output produced by another tool, pass `eval --test-id ID --scorer json --output-file response.json` with the prompt name, version, and model. Use `--output-file -` for stdin. The provider example also accepts `--scorer json`.
212
+
213
+ ## JSON snapshots and SQLite backups
214
+
215
+ Use JSON when you want to inspect changes in Git, transfer the logical data, or load it into a new database.
216
+
217
+ ```bash
218
+ promptdb --db prompts.db export > promptdb.json
219
+ promptdb --db restored.db import promptdb.json
220
+ promptdb --db restored.db history country
221
+ ```
222
+
223
+ The snapshot includes templates, metadata, tags, inputs, expected values, outputs, dates, IDs, and version counters. The same database state produces the same UTF-8 JSON. Import requires a new or unused database and validates the complete snapshot in one transaction. Use `db.export_json()` to get a string and `db.import_json(payload)` to restore it from Python.
224
+
225
+ The JSON format is identified by `format: "evals-promptdb"` and `version: 4`. It stores chat messages as JSON arrays and preserves which cases are archived. Imports also accept formats 1–3. You can check a snapshot into Git and import it into a new SQLite file in CI.
226
+
227
+ Use SQLite backup when you want a standalone database file. The source can be open in other connections. The destination must be a new path in an existing directory on a filesystem that supports hard links.
228
+
229
+ ```bash
230
+ promptdb --db prompts.db backup prompts-copy.db
231
+ promptdb --db prompts-copy.db history country
232
+ ```
233
+
234
+ The equivalent API is `db.backup("prompts-copy.db")`. Open the copied file directly to use it. Use a separate `PromptDB` instance per thread. Set `PromptDB("prompts.db", timeout=30)` to configure the lock wait in seconds. Set `create=False` to require an existing database, or use `PromptDB(":memory:")` for a temporary database.
235
+
236
+ Use `PromptDB("prompts.db", read_only=True)` or `promptdb --read-only` for an existing, current-schema database that should stay untouched. Reads, comparisons, exports, and backups can use that connection. `db.check()` returns SQLite integrity and foreign-key findings.
237
+
238
+ ```bash
239
+ promptdb --db empty.db init
240
+ promptdb --db prompts.db --read-only check
241
+ promptdb --db prompts.db --read-only export --output snapshot.json
242
+ ```
243
+
244
+ `export --output` creates a new UTF-8 file without replacing an existing path. The CLI also uses UTF-8 for prompt and JSON pipes, and `import` accepts snapshots with a UTF-8 BOM.
245
+
246
+ ## Provider examples
247
+
248
+ Run the Python quickstart first. From the checkout, `python -m examples.evaluate` runs saved cases over any number of versions with one shared run ID. It supports Ollama, OpenAI, Anthropic, OpenAI-compatible Chat Completions servers, and a deterministic uppercase function for offline tests.
249
+
250
+ ```bash
251
+ python -m examples.evaluate ollama country 1 2 --model qwen2.5-coder:7b --run-id ollama-smoke
252
+ promptdb compare country 1 2 --model ollama/qwen2.5-coder:7b --run-id ollama-smoke --min-coverage 1
253
+ ```
254
+
255
+ Ollama uses its local HTTP API and an installed model. Set `--ollama-host` to choose a server. OpenAI uses the optional `openai` SDK and `OPENAI_API_KEY`. Anthropic uses the optional `anthropic` SDK and `ANTHROPIC_API_KEY`. Pass `--model` with the ID for that provider. The script prints the model key and run ID to use with `promptdb compare`. [Ollama Chat API](https://docs.ollama.com/api/chat) · [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages)
256
+
257
+ Use `--timeout` to allow for a cold start, `--max-tokens` to limit generated tokens, or `--ollama-context` to set the local context size.
258
+
259
+ Use `openai-compatible --api-base` with a base URL such as `http://127.0.0.1:8000/v1` for a server that exposes Chat Completions. Set `PROMPTDB_ENDPOINT_API_KEY` if that server requires a bearer token. The example sends developer messages as system instructions to Ollama and compatible servers. Anthropic takes system and developer instructions before the first conversation turn. [vLLM compatible server documentation](https://docs.vllm.ai/en/latest/serving/openai_compatible_server/)
260
+
261
+ ### OpenAI from Python
262
+
263
+ Run the Python quickstart first. Install the optional SDK with `python -m pip install openai` and configure `OPENAI_API_KEY`. The generator below sends the rendered template to the Responses API. Evals PromptDB stores the returned text and score locally. [OpenAI Responses API reference](https://developers.openai.com/api/reference/python/resources/responses/methods/create).
264
+
265
+ ```python
266
+ from openai import OpenAI
267
+ from promptdb import PromptDB
268
+
269
+ client = OpenAI()
270
+ model = "gpt-4o-mini"
271
+
272
+ def generate(text):
273
+ return client.responses.create(
274
+ model=model,
275
+ input=text,
276
+ store=False,
277
+ ).output_text
278
+
279
+ with PromptDB("prompts.db", create=False) as db:
280
+ runs = db.run_tests("country", version=2, model=model, generate=generate)
281
+ for run in runs:
282
+ print(run.test_id, run.score, run.output)
283
+ ```
284
+
285
+ ## Development
286
+
287
+ Run the test suite with the standard library.
288
+
289
+ ```bash
290
+ python -m unittest discover -s tests -v
291
+ ```
292
+
293
+ GitHub Actions tests CPython 3.10–3.15 and PyPy 3.11 on Linux, CPython 3.10 and 3.15 on Windows, and CPython 3.15 on macOS. The wheel includes type annotations for consumers and has no required third-party runtime dependencies. Use the packaging tools below to build and check the distributions locally.
294
+
295
+ ```bash
296
+ python -m pip install build twine
297
+ python -m build
298
+ python -m twine check --strict dist/*
299
+ ```
300
+
301
+ [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
@@ -0,0 +1,271 @@
1
+ <div align="center">
2
+ <img src="assets/evals-promptdb.png" width="128" height="128" alt="Icono de Evals PromptDB">
3
+ <h1>Evals PromptDB</h1>
4
+ <p><strong>Prompts de LLM versionados y evaluaciones en SQLite local.</strong></p>
5
+ <p>
6
+ <a href="https://github.com/Arcynox/EvalsPromptDB/actions/workflows/ci.yml"><img src="https://github.com/Arcynox/EvalsPromptDB/actions/workflows/ci.yml/badge.svg" alt="Estado de CI en GitHub Actions"></a>
7
+ <a href="#instalación"><img src="https://img.shields.io/badge/Python-3.10%2B-6d4aff" alt="Python 3.10 o posterior"></a>
8
+ <a href="LICENSE"><img src="https://img.shields.io/badge/Licencia-MIT-27896d" alt="Licencia MIT"></a>
9
+ </p>
10
+ <p>
11
+ <a href="README.md">English</a> · <a href="#instalación">Instalación</a> · <a href="#inicio-rápido-en-python">Inicio en Python</a> · <a href="#inicio-rápido-en-la-terminal">Inicio en la CLI</a> · <a href="#ejemplos-de-proveedores">Proveedores</a>
12
+ </p>
13
+ </div>
14
+
15
+ Guardá plantillas, casos, salidas y puntuaciones en un archivo `.db`. Usá la API de Python en tu aplicación o la CLI en scripts y CI. El núcleo usa la biblioteca estándar de Python.
16
+
17
+ ## Flujo de trabajo
18
+
19
+ | Paso | Qué podés hacer |
20
+ | --- | --- |
21
+ | **Versionar** | Guardá plantillas inmutables y elegí la versión activa por etiqueta. |
22
+ | **Evaluar** | Ejecutá los mismos casos sobre varias versiones con el generador y la función de puntuación que elijas. |
23
+ | **Comparar y promover** | Revisá diffs, puntuaciones y cobertura. Aplicá controles en CI y hacé rollback moviendo la etiqueta. |
24
+ | **Compartir** | Versioná JSON determinista en Git o transferí una copia consistente de SQLite. |
25
+
26
+ ## Instalación
27
+
28
+ Usá Python 3.10 o posterior. Instalá el paquete desde este directorio.
29
+
30
+ ```bash
31
+ python -m pip install .
32
+ promptdb --version
33
+ ```
34
+
35
+ La distribución se llama `evals-promptdb`. Importá `PromptDB` desde `promptdb` y ejecutá `promptdb` o `python -m promptdb`. También podés ejecutar `python -m promptdb` desde este directorio sin instalar el paquete.
36
+
37
+ Si instalaste PromptDB 0.1.0 o 0.2.0 desde este proyecto, desinstalá la distribución anterior (`promptdb` o `promptdb-local`, respectivamente) en ese entorno antes de instalar `evals-promptdb`. Una conexión de escritura migra los archivos SQLite anteriores en una sola transacción. Usá el paquete actualizado para abrir los archivos migrados.
38
+
39
+ ## Inicio rápido en Python
40
+
41
+ Ejecutá el ejemplo en un directorio sin un archivo `prompts.db`. Las funciones de ejemplo simulan las llamadas a un modelo para que puedas probarlo sin conexión.
42
+
43
+ ```python
44
+ from promptdb import PromptDB
45
+
46
+ with PromptDB("prompts.db") as db:
47
+ v1 = db.save(
48
+ "pais",
49
+ "Indicá el país al que pertenece {{ciudad}}.",
50
+ tags=["produccion"],
51
+ metadata={"equipo": "ejemplos"},
52
+ )
53
+ v2 = db.save(
54
+ "pais",
55
+ "Devolvé solo el nombre del país al que pertenece {{ciudad}}.",
56
+ tags=["experimento"],
57
+ )
58
+ caso = db.add_test("pais", input={"ciudad": "Madrid"}, expected="España")
59
+
60
+ actual = db.get("pais", tag="produccion")
61
+ print(actual.render(caso.input))
62
+
63
+ db.run_tests("pais", version=v1.version, model="demo",
64
+ generate=lambda texto: "Madrid está en España.", run_id="inicio-rapido")
65
+ db.run_tests("pais", version=v2.version, model="demo",
66
+ generate=lambda texto: "España", run_id="inicio-rapido")
67
+
68
+ resultado = db.compare("pais", [v1.version, v2.version], model="demo", run_id="inicio-rapido")
69
+ print(resultado.versions[1].diff)
70
+ print(resultado.versions[1].coverage) # 1.0
71
+ print(resultado.best.prompt.version) # 2
72
+
73
+ db.promote("pais", v2.version)
74
+ db.promote("pais", v1.version) # Vuelve a producción la primera versión
75
+ ```
76
+
77
+ El mismo caso se aplica a las dos versiones. Por defecto, `run_tests()` puntúa por coincidencia exacta tras quitar el espacio en blanco de los extremos. Una función `scorer(output, expected)` puede devolver cualquier puntuación numérica de 0 a 1 y es obligatoria si el valor esperado tiene un tipo distinto de texto.
78
+
79
+ ## Prompts de chat
80
+
81
+ Guardá mensajes de texto ordenados cuando el modelo necesite distinguir las instrucciones de los turnos de conversación. Podés usar variables en cada mensaje. Los roles admitidos son `system`, `developer`, `user` y `assistant`.
82
+
83
+ ```python
84
+ from promptdb import PromptDB
85
+
86
+ with PromptDB(":memory:") as db:
87
+ prompt = db.save("traducir", messages=[
88
+ {"role": "system", "content": "Traducí el texto del usuario a {{idioma}}."},
89
+ {"role": "user", "content": "{{texto}}"},
90
+ ])
91
+ entrada = {"idioma": "español", "texto": "Good morning"}
92
+ mensajes = prompt.render_messages(entrada)
93
+ db.add_test("traducir", input=entrada, expected="Buenos días")
94
+ db.run_tests("traducir", model="demo", generate_messages=lambda conversación: "Buenos días")
95
+ ```
96
+
97
+ `Prompt.kind` indica si el prompt es `text` o `chat`. `render_messages()` también admite prompts de texto y devuelve un único mensaje de usuario. `render()` devuelve texto JSON para prompts de chat. Usá `generate_messages` para pasar los mensajes directamente al cliente del modelo.
98
+
99
+ ```bash
100
+ promptdb --db chat.db save traducir --messages - <<'JSON'
101
+ [{"role":"system","content":"Traducí a {{idioma}}."},{"role":"user","content":"{{texto}}"}]
102
+ JSON
103
+ promptdb --db chat.db get traducir --input '{"idioma":"español","texto":"Good morning"}'
104
+ ```
105
+
106
+ ## Inicio rápido en la terminal
107
+
108
+ Los comandos usan una base nueva llamada `cli.db`.
109
+
110
+ ```bash
111
+ promptdb --db cli.db save pais --template 'Indicá el país al que pertenece {{ciudad}}.' --tag produccion
112
+ promptdb --db cli.db save pais --template 'Devolvé solo el país de {{ciudad}}.' --tag experimento
113
+ promptdb --db cli.db get pais --tag produccion --input '{"ciudad":"Madrid"}'
114
+ promptdb --db cli.db add-test pais --input '{"ciudad":"Madrid"}' --expected '"España"'
115
+ promptdb --db cli.db eval pais --version 1 --model demo --run-id demo-1 --test-id 1 --score 0.83
116
+ promptdb --db cli.db eval pais --version 2 --model demo --run-id demo-1 --test-id 1 --score 0.87
117
+ promptdb --db cli.db compare pais 1 2 --model demo --run-id demo-1 --min-score 0.85 --min-coverage 1 --max-regression 0.02
118
+ promptdb --db cli.db promote pais 2
119
+ ```
120
+
121
+ <details>
122
+ <summary>Ejemplo de salida de la comparación</summary>
123
+
124
+ ```text
125
+ Version Variables Added Removed Evals Avg score Cases Case avg Paired delta
126
+ 1 ciudad - - 1 0.830 1/1 0.830 -
127
+ 2 ciudad - - 1 0.870 1/1 0.870 +0.040 (1)
128
+ ```
129
+
130
+ </details>
131
+
132
+ Usá `save --from-file plantilla.txt` para leer una plantilla de varias líneas en UTF-8 y `--from-file -` para leer de la entrada estándar. `get --json` devuelve el registro completo, `get --input` aplica los valores a la plantilla y `compare --json` devuelve la comparación en un formato apto para scripts. Ejecutá `promptdb --help` para ver todos los comandos.
133
+
134
+ ### Controles de calidad en CI
135
+
136
+ La última versión de la comparación es la candidata. La primera es la base. Pasá el mismo `--model` y `--run-id` de las puntuaciones registradas para evaluar un solo modelo y una sola corrida.
137
+
138
+ | Parámetro | Condición para aprobar |
139
+ | --- | --- |
140
+ | `--min-score 0.85` | La candidata alcanza la puntuación mínima. Con cobertura o regresión, cada caso evaluado pesa lo mismo y solo cuentan puntuaciones asociadas a un caso. Por sí solo, `--min-score` usa el promedio de todos los registros de evaluación que coinciden. |
141
+ | `--min-coverage 1` | La candidata tiene puntuaciones para el 100% de los casos elegibles. Si omitís `--test-id`, son elegibles todos los casos del prompt. Las repeticiones de un caso cuentan una vez para la cobertura. |
142
+ | `--max-regression 0.02` | El promedio de la candidata cae como máximo 0.02 puntos frente a la base en los casos compartidos. La cobertura compartida debe alcanzar `--min-coverage`, o el 100% si omitís ese parámetro. |
143
+
144
+ Un control fallido devuelve `3`, incluso cuando faltan puntuaciones o casos requeridos. Devuelve `0` si aprueba, `1` ante errores de ejecución y `2` ante errores de sintaxis. El informe JSON incluye `case_scores`, `coverage`, `case_average_score` y `paired` por versión, además del promedio de registros.
145
+
146
+ ## API de Python
147
+
148
+ | Operación | Comportamiento |
149
+ | --- | --- |
150
+ | `save(name, template, ...)` | Crea una versión de texto o admite `messages=` para chat. También acepta `version`, `variables`, `model`, `temperature`, `metadata` y `tags`. |
151
+ | `get(name, version="latest", tag=None)` | Devuelve la versión de mayor número que coincide con los filtros. Si pasás un número y una etiqueta, deben coincidir ambos. Si falta el registro, lanza `KeyError`. |
152
+ | `Prompt.render(values)` | Reemplaza los marcadores detectados una sola vez. Admite valores adicionales. Una variable faltante produce `KeyError`. |
153
+ | `list(tags=())` y `history(name)` | Listan versiones. El filtro exige todas las etiquetas solicitadas. El historial va de la versión más antigua a la más reciente. |
154
+ | `set_tags(name, version, tags)` | Reemplaza las etiquetas de una versión. El equivalente en CLI es `tag`. |
155
+ | `promote(name, version, tag="produccion")` | Mueve una etiqueta a una sola versión del prompt en una transacción. |
156
+ | `add_test(name, input=..., expected=...)` y `list_tests(name)` | Guardan casos compartidos por todas las versiones de un prompt y listan los casos activos. |
157
+ | `get_test(name, test_id)` | Lee un caso por su identificador, incluidos los casos archivados. |
158
+ | `set_test_archived(name, test_id, archived=True)` y `replace_test(...)` | Permiten actualizar la suite activa y seguir consultando el caso anterior y sus evaluaciones. |
159
+ | `add_eval(name, version=..., score=..., model=..., ...)` | Registra una puntuación y admite `test_id`, `run_id`, `output`, `metadata` y la fecha original `created_at`. |
160
+ | `run_tests(name, model=..., generate=..., ...)` | Aplica las variables a los casos activos, llama al generador y registra los resultados en una transacción. Elegí una versión o etiqueta y pasá `test_ids` para evaluar un subconjunto. |
161
+ | `await arun_tests(name, model=..., generate=..., ...)` | Espera un generador de texto o mensajes y admite un evaluador síncrono o asíncrono. |
162
+ | `compare(name, versions=None, ...)` y `list_evals(name, ...)` | Consultan evaluaciones guardadas con filtros por corrida, modelo, caso y fecha. |
163
+ | `delete(name, version)` | Elimina una versión, sus etiquetas y sus evaluaciones. Los casos quedan asociados al nombre del prompt. |
164
+
165
+ Los marcadores como `{{ciudad}}` y `{{ ciudad }}` se detectan en orden de aparición. Si pasás `variables` de forma explícita, usá el mismo conjunto que en la plantilla. Los números aumentan por nombre, incluso después de borrar una versión. Para editar una plantilla o su configuración, guardá una versión nueva.
166
+
167
+ Usá un `datetime` con zona horaria para `created_at`, `since` y `until`. La CLI acepta fechas ISO 8601 con desplazamiento, como `2026-11-12T10:00:00-03:00`. Los intervalos incluyen `since` y excluyen `until`. La primera versión solicitada es la base del diff. `resultado.best` devuelve la versión con mayor `average_score` de los registros que coinciden y, en caso de empate, respeta el orden de comparación. Las versiones sin evaluaciones coincidentes tienen promedio `None`. Usá el mismo modelo y un conjunto consistente de casos cuando la puntuación decida un paso de CI.
168
+
169
+ Una tanda toma la versión y los casos visibles al inicio. Las llamadas al modelo y la puntuación ocurren fuera de la transacción de SQLite. Si falla la sustitución de variables, el generador, la evaluación o la escritura, la tanda no deja resultados parciales. `run_tests()` asigna un identificador por defecto. Pasá el mismo `run_id` a la base y la candidata cuando las evalúes juntas.
170
+
171
+ Usá `arun_tests()` con un cliente asíncrono. Las transacciones de SQLite quedan fuera de las esperas al proveedor. Los dos métodos admiten `tag` para seleccionar la versión desplegada y `test_ids` para ejecutar casos activos en el orden solicitado. La cobertura se calcula sobre los casos elegibles de cada comparación.
172
+
173
+ ### Mantenimiento de casos de prueba
174
+
175
+ Usá `archive-test` para retirar un caso o `restore-test` para volver a activarlo. Con `replace-test NOMBRE ID --input ... --expected ...`, archivás el caso anterior y creás uno nuevo con su propio identificador en una transacción. `get-test` y `evals` siguen mostrando el caso original y sus puntuaciones. `run_tests`, `tests` y `compare` usan los casos activos por defecto. Para una auditoría, usá `include_archived=True` en `list_tests()` o `compare()`, o `--include-archived` en `tests` o `compare`.
176
+
177
+ ### Evaluar salidas estructuradas
178
+
179
+ Importá `json_match` con `from promptdb.scorers import json_match` y pasá `scorer=json_match` a `run_tests()` para evaluar JSON. El orden de los campos y los espacios irrelevantes se ignoran. Se respeta el orden de los arrays y se distingue entre números y booleanos. El JSON malformado recibe cero y su salida se guarda en la evaluación.
180
+
181
+ Para puntuar la salida de otra herramienta, usá `eval --test-id ID --scorer json --output-file respuesta.json` junto al nombre del prompt, la versión y el modelo. Pasá `--output-file -` para leer de la entrada estándar. El ejemplo de proveedores también admite `--scorer json`.
182
+
183
+ ## Snapshots JSON y copias de seguridad SQLite
184
+
185
+ Usá JSON para revisar cambios en Git, transferir los datos o cargar una base nueva.
186
+
187
+ ```bash
188
+ promptdb --db prompts.db export > promptdb.json
189
+ promptdb --db restaurada.db import promptdb.json
190
+ promptdb --db restaurada.db history pais
191
+ ```
192
+
193
+ El snapshot incluye plantillas, metadata, etiquetas, entradas, valores esperados, salidas, fechas, identificadores y contadores de versión. El mismo estado produce el mismo JSON en UTF-8. La importación requiere una base nueva o sin uso y valida el snapshot completo en una transacción. Usá `db.export_json()` para obtener el texto y `db.import_json(payload)` para restaurarlo desde Python.
194
+
195
+ El formato JSON se identifica con `format: "evals-promptdb"` y `version: 4`. Guarda los mensajes de chat como arrays JSON y conserva el estado de los casos archivados. La importación también admite los formatos 1 a 3. Podés guardar el snapshot en Git e importarlo a un archivo SQLite nuevo en CI.
196
+
197
+ Usá una copia de seguridad SQLite si necesitás un archivo de base de datos listo para abrir. Otras conexiones pueden seguir usando el archivo original. Elegí un archivo nuevo en un directorio existente cuyo sistema de archivos admita enlaces duros.
198
+
199
+ ```bash
200
+ promptdb --db prompts.db backup prompts-copia.db
201
+ promptdb --db prompts-copia.db history pais
202
+ ```
203
+
204
+ La API equivalente es `db.backup("prompts-copia.db")`. Abrí la copia directamente para usarla. Usá una instancia de `PromptDB` por hilo. Configurá el tiempo de espera ante bloqueos con `PromptDB("prompts.db", timeout=30)` en segundos. Pasá `create=False` para exigir una base existente o `PromptDB(":memory:")` para usar una base temporal.
205
+
206
+ Usá `PromptDB("prompts.db", read_only=True)` o `promptdb --read-only` para abrir una base existente con el esquema actual en solo lectura. Esa conexión permite consultar, comparar, exportar y respaldar. `db.check()` informa problemas de integridad o de claves foráneas.
207
+
208
+ ```bash
209
+ promptdb --db vacia.db init
210
+ promptdb --db prompts.db --read-only check
211
+ promptdb --db prompts.db --read-only export --output snapshot.json
212
+ ```
213
+
214
+ `export --output` crea un archivo UTF-8 nuevo y conserva cualquier archivo existente en esa ruta. La CLI usa UTF-8 para prompts y JSON en pipes, e `import` admite snapshots UTF-8 con BOM.
215
+
216
+ ## Ejemplos de proveedores
217
+
218
+ Corré primero el inicio rápido en Python. Desde el directorio del proyecto, `python -m examples.evaluate` ejecuta casos guardados sobre varias versiones con un identificador de corrida compartido. Admite Ollama, OpenAI, Anthropic, servidores con Chat Completions compatible con OpenAI y una función determinista de mayúsculas para pruebas sin conexión.
219
+
220
+ ```bash
221
+ python -m examples.evaluate ollama pais 1 2 --model qwen2.5-coder:7b --run-id ollama-smoke
222
+ promptdb compare pais 1 2 --model ollama/qwen2.5-coder:7b --run-id ollama-smoke --min-coverage 1
223
+ ```
224
+
225
+ Ollama usa su API HTTP local y un modelo instalado. Pasá `--ollama-host` si querés elegir otro servidor. OpenAI usa el SDK opcional `openai` y `OPENAI_API_KEY`. Anthropic usa el SDK opcional `anthropic` y `ANTHROPIC_API_KEY`. Indicá el identificador del modelo con `--model`. El script muestra la clave del modelo y el identificador necesarios para `promptdb compare`. [API de Ollama Chat](https://docs.ollama.com/api/chat) · [API de Anthropic Messages](https://platform.claude.com/docs/en/api/messages)
226
+
227
+ Usá `--timeout` para dar más tiempo al primer arranque, `--max-tokens` para limitar la salida o `--ollama-context` para configurar el tamaño de contexto local.
228
+
229
+ Usá `openai-compatible --api-base` con una URL base como `http://127.0.0.1:8000/v1` para un servidor que exponga Chat Completions. Configurá `PROMPTDB_ENDPOINT_API_KEY` si ese servidor requiere un token. El ejemplo envía los mensajes `developer` como instrucciones `system` a Ollama y a los servidores compatibles. Con Anthropic, ubicá las instrucciones `system` y `developer` antes del primer turno de conversación. [Documentación del servidor compatible de vLLM](https://docs.vllm.ai/en/latest/serving/openai_compatible_server/)
230
+
231
+ ### OpenAI desde Python
232
+
233
+ Corré primero el inicio rápido en Python. Instalá el SDK opcional con `python -m pip install openai` y configurá `OPENAI_API_KEY`. El generador envía la plantilla con las variables sustituidas a la API Responses. Evals PromptDB guarda localmente el texto devuelto y la puntuación. [Referencia de la API Responses](https://developers.openai.com/api/reference/python/resources/responses/methods/create).
234
+
235
+ ```python
236
+ from openai import OpenAI
237
+ from promptdb import PromptDB
238
+
239
+ client = OpenAI()
240
+ modelo = "gpt-4o-mini"
241
+
242
+ def generar(texto):
243
+ return client.responses.create(
244
+ model=modelo,
245
+ input=texto,
246
+ store=False,
247
+ ).output_text
248
+
249
+ with PromptDB("prompts.db", create=False) as db:
250
+ evaluaciones = db.run_tests("pais", version=2, model=modelo, generate=generar)
251
+ for evaluacion in evaluaciones:
252
+ print(evaluacion.test_id, evaluacion.score, evaluacion.output)
253
+ ```
254
+
255
+ ## Desarrollo
256
+
257
+ Corré las pruebas con la biblioteca estándar.
258
+
259
+ ```bash
260
+ python -m unittest discover -s tests -v
261
+ ```
262
+
263
+ GitHub Actions ejecuta pruebas en CPython 3.10 a 3.15 y PyPy 3.11 en Linux, CPython 3.10 y 3.15 en Windows, y CPython 3.15 en macOS. El wheel incluye anotaciones de tipos y funciona sin dependencias externas obligatorias. Usá estas herramientas para construir y revisar las distribuciones en local.
264
+
265
+ ```bash
266
+ python -m pip install build twine
267
+ python -m build
268
+ python -m twine check --strict dist/*
269
+ ```
270
+
271
+ [Historial de cambios](CHANGELOG.md) · [Licencia MIT](LICENSE)