zanii-evolve 0.1.0__tar.gz

zanii_evolve-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

zanii_evolve-0.1.0/NOTICE

@@ -0,0 +1,17 @@
+Zanii Evolve
+Copyright 2026 zaniiai agency.
+
+This product includes software derived from the RRSI reference implementation:
+  Copyright 2026 Google LLC
+  Copyright 2026 The rrsi Authors
+Licensed under the Apache License, Version 2.0. Files carrying these notices
+were modified by zaniiai agency; modified files say so in their headers.
+
+third_party/harbor_terminus2
+  The Terminus-2 agent from harbor (https://github.com/laude-institute/harbor),
+  Apache License 2.0; see third_party/harbor_terminus2/LICENSE.
+
+third_party/archipelago
+  The react_toolbelt agent and runner from archipelago
+  (https://github.com/Mercor-Intelligence/archipelago),
+  Apache License 2.0; see third_party/archipelago/LICENSE.

zanii_evolve-0.1.0/PKG-INFO

@@ -0,0 +1,407 @@
+Metadata-Version: 2.4
+Name: zanii-evolve
+Version: 0.1.0
+Summary: Regularized self-improvement of LLM agent harnesses: gains that hold up out of distribution, with verifiable change history
+Author: zaniiai agency
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/vigilancetrent/zanii-evolve
+Project-URL: Source, https://github.com/vigilancetrent/zanii-evolve
+Project-URL: Issues, https://github.com/vigilancetrent/zanii-evolve/issues
+Keywords: llm,agents,agent-harness,self-improvement,evaluation,prompt-optimization,auditability,proof-of-action
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: anthropic[vertex]>=0.40
+Provides-Extra: agentic
+Requires-Dist: fastmcp>=2.0; extra == "agentic"
+Requires-Dist: litellm>=1.50; extra == "agentic"
+Requires-Dist: loguru>=0.7; extra == "agentic"
+Requires-Dist: mcp>=1.0; extra == "agentic"
+Requires-Dist: openai>=1.0; extra == "agentic"
+Requires-Dist: pydantic>=2.0; extra == "agentic"
+Requires-Dist: pydantic-settings>=2.0; extra == "agentic"
+Requires-Dist: httpx>=0.27; extra == "agentic"
+Requires-Dist: tenacity>=8.0; extra == "agentic"
+Requires-Dist: pymupdf>=1.24; extra == "agentic"
+Requires-Dist: zaniidb-agent-memory>=0.11; python_version >= "3.11" and extra == "agentic"
+Provides-Extra: coding
+Requires-Dist: harbor>=0.18; extra == "coding"
+Requires-Dist: zaniidb-agent-memory>=0.11; python_version >= "3.11" and extra == "coding"
+Provides-Extra: provable
+Requires-Dist: zanii>=0.25; extra == "provable"
+Provides-Extra: memory
+Requires-Dist: zaniidb-agent-memory>=0.11; python_version >= "3.11" and extra == "memory"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vigilancetrent/zanii-evolve/main/assets/banner.svg" width="100%" alt="Zanii Evolve">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/zanii-evolve/"><img src="https://img.shields.io/pypi/v/zanii-evolve?color=0f766e" alt="PyPI"></a>
+  <a href="https://pypi.org/project/zanii-evolve/"><img src="https://img.shields.io/pypi/pyversions/zanii-evolve" alt="Python versions"></a>
+  <a href="https://github.com/vigilancetrent/zanii-evolve/actions/workflows/tests.yml"><img src="https://github.com/vigilancetrent/zanii-evolve/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://github.com/vigilancetrent/zanii-evolve/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
+</p>
+
+Zanii Evolve improves an LLM agent by editing its **harness** (the prompts,
+control flow, tools, skills and memory around a frozen model), and only keeps
+the edits that survive a regularized search. A gain has to clear the
+measurement noise, pay for any extra tokens it costs, and pass a leakage screen
+before it becomes the new baseline. The result is an agent that gets better on
+work it has not seen, not one that memorized its test set.
+
+Every accepted change is a git commit with a stated hypothesis and a measured
+effect. A run ends with a certificate you can hand to a reviewer, optionally
+signed so that anyone can verify who issued it without trusting you.
+
+Maintained by [zaniiai agency](https://github.com/zaniiai).
+
+---
+
+## Contents
+
+- [Why](#why)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Bring your own tasks](#bring-your-own-tasks)
+- [Certificates, signing and the registry](#certificates-signing-and-the-registry)
+- [Memory](#memory)
+- [Dashboard and HTTP API](#dashboard-and-http-api)
+- [Configuration](#configuration)
+- [Command reference](#command-reference)
+- [Project layout](#project-layout)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+## Why
+
+Searching over harness edits against a fixed task set works, and it overfits:
+the harness learns the tasks, and the in-distribution gain shrinks or vanishes
+on anything new. Zanii Evolve keeps the edit space open and constrains *how the
+search moves* instead.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vigilancetrent/zanii-evolve/main/assets/pipeline.svg" width="100%" alt="One round: analyze, propose, screen, evaluate, select; evidence out">
+</p>
+
+**On the proposal side**
+
+- An annealed edit budget limits how many independent changes one candidate may bundle, so late gains are attributable.
+- The proposer sees the full edit history, so a hypothesis that already failed is not tried again.
+- When progress stalls, slots are reserved for components the run has never touched.
+
+**On the selection side**
+
+- A critic screens every diff for task-specific logic before any evaluation is spent on it.
+- A noise-adjusted floor rejects gains that sit inside evaluation variance.
+- A cost rule requires added inference tokens to be paid for by measured gain.
+- Components that stop contributing are flagged for pruning.
+
+Each rule maps to one place in the code:
+
+| Rule | Code |
+|---|---|
+| Score and cost estimate | `zanii_evolve/evaluate.py` (`aggregate`; a missing trial scores 0 with the full denominator) |
+| Annealed edit budget | `zanii_evolve/schedule.py` (`edit_budget`), enforced in `propose.py` |
+| Edit history, tried set, recent yield, stall flag | `zanii_evolve/history.py` |
+| Failure analysis | `zanii_evolve/analyst.py`, `digester.py` |
+| Leakage critic | `zanii_evolve/critic.py` (domain denylist plus LLM review, bounded repair) |
+| Noise floor, cost rule, score or cost objective | `zanii_evolve/selection.py` |
+| Noise band calibration | `zanii_evolve/calibrate.py` (bootstrap over base trials, or repeated base runs) |
+| Non-compensatory domain guards | `Domain.guards` (for example a valid-rate drop in engineering design) |
+
+## Install
+
+```bash
+pip install zanii-evolve                   # search core, providers, certificates, brief engine
+pip install "zanii-evolve[provable]"       # + signed certificate receipts (zanii)
+pip install "zanii-evolve[memory]"         # + ZaniiDB memory backend (Python 3.11+)
+```
+
+The command line, the bundled domains and the starting harnesses live in the
+repository. To run evolutions, clone it:
+
+```bash
+git clone https://github.com/vigilancetrent/zanii-evolve.git
+cd zanii-evolve
+pip install -e ".[dev]"
+python -m pytest tests
+```
+
+Requires Python 3.10 or newer. Benchmark runners keep their own environments:
+harbor for the coding domain, and a Python 3.11 environment with
+`pip install -e ".[agentic]"` for the workspace and engineering domains, pointed
+to by `ZANII_EVOLVE_AGENT_PYTHON`.
+
+## Quickstart
+
+Pick a model provider. The model string names it:
+
+| Model string | Backend | Credentials |
+|---|---|---|
+| `anthropic/<model>` | Anthropic API | `ANTHROPIC_API_KEY` |
+| `vertex/<model>` | Vertex AI, round-robin over projects | `gcloud auth application-default login`, `ZANII_EVOLVE_VERTEX_PROJECTS` |
+| `openai/<model>` | Any OpenAI-compatible endpoint (OpenAI, LiteLLM, vLLM) | `ZANII_EVOLVE_OPENAI_BASE_URL`, `ZANII_EVOLVE_OPENAI_API_KEY` |
+| `ollama/<model>` | A local Ollama server, for on-prem and air-gapped use | `ZANII_EVOLVE_OLLAMA_BASE_URL` (no key is ever sent) |
+
+Custom backends register with `ZANII_EVOLVE_PROVIDERS="name=module:Class"`.
+
+Every domain then follows the same lifecycle:
+
+```bash
+python zanii_evolve.py --domain marketing smoke       # liveness check on a couple of tasks
+python zanii_evolve.py --domain marketing baseline    # measure the starting harness H0
+python zanii_evolve.py --domain marketing run         # evolve; resumable, `touch runs/marketing/STOP` to stop
+python zanii_evolve.py --domain marketing status      # incumbent against H0
+python zanii_evolve.py --domain marketing heldout --label final   # held-out split, never used for selection
+```
+
+Each round drafts candidates in separate git worktrees on branches off
+`evolve/<domain>`, screens and evaluates them, and fast-forwards the branch to
+the winner, so the current best harness is always a commit.
+
+### Bundled domains
+
+| Domain | Evolve set | Out-of-distribution checks | Notes |
+|---|---|---|---|
+| [`coding`](https://github.com/vigilancetrent/zanii-evolve/tree/main/domains/coding) | Terminal-Bench 2.1 | SWE-bench Verified | Docker and harbor |
+| [`workspace`](https://github.com/vigilancetrent/zanii-evolve/tree/main/domains/workspace) | Harvey LAB | JobBench, GDPval, APEX-Agents | Harvey LAB checkout at a pinned commit |
+| [`eng`](https://github.com/vigilancetrent/zanii-evolve/tree/main/domains/eng) | EngDesign | EngDesign v1, Frontier-Eng | grading venv, jailed tool gateway |
+| [`marketing`](https://github.com/vigilancetrent/zanii-evolve/tree/main/domains/marketing) | 48 briefs, 8 fictional clients | held-out split | brief domain, no adapter code |
+| [`memory`](https://github.com/vigilancetrent/zanii-evolve/tree/main/domains/memory) | 40 multi-session histories | held-out split | exercises ZaniiDB recall and supersede |
+
+Results are reported per domain for the evolve, held-out and out-of-distribution
+splits, always against H0 measured in the same window with the same frozen
+model. Published numbers will ship with signed certificates.
+
+## Bring your own tasks
+
+Any work that is "a brief in, a text deliverable out, graded by checks and a
+rubric" needs no adapter code.
+
+```bash
+python zanii_evolve.py --domain acme init-domain                    # scaffold domains/acme
+python zanii_evolve.py --domain acme import-tasks briefs.csv --replace
+python zanii_evolve.py --domain acme redteam --n 10                 # prompt-injection split
+python zanii_evolve.py --domain acme ingest-traces prod.jsonl --rubric "Answers the question|No made-up facts"
+```
+
+A spreadsheet needs one column, `brief`. Optional columns are `id`, `split`,
+`kind`, `must_include` and `must_not_include` (`|`-separated), `max_words`,
+`min_words`, `max_chars`, and `rubric` (`|`-separated pass/fail criteria). Any
+other column (`client`, `audience`, ...) reaches the harness as context. Rows
+without a split get a seeded evolve/held-out draw, and the whole file is
+validated before anything is written.
+
+The underlying task format is one JSON object per line:
+
+```json
+{"id": "acme-001", "split": "evolve", "kind": "promotional email", "brief": "...",
+ "checks": [{"type": "max_words", "value": 150}, {"type": "must_include", "values": ["Book now"]}],
+ "rubric": [{"criterion": "Matches the brand voice.", "weight": 1}]}
+```
+
+Checks: `max_words`, `min_words`, `max_chars`, `must_include`, `must_include_any`,
+`must_not_include`, `regex`, `regex_count`, `field_max_chars`. Rubric criteria are
+judged pass/fail by `judge_model`. Checks, rubric and expected answers never
+reach the harness, and grading runs outside the candidate's editable tree, so a
+candidate cannot edit its own judge.
+
+**Production traces.** `ingest-traces` accepts records with `input`, `prompt`
+or an OpenTelemetry `gen_ai.prompt` attribute. Records with negative feedback
+come first, duplicates are dropped, emails, phone numbers and card-like numbers
+are redacted, and re-running on the same file adds nothing. Production outputs
+are never copied into a task.
+
+**Red-team split.** Each variant embeds an instruction carrying a unique canary
+string that the deliverable must not contain, keeps the original checks, and
+lives in its own `redteam` split: `heldout --label rt --set redteam`.
+
+**Judge calibration.** Before trusting a rubric judge with a run, grade a
+handful of deliverables by hand and compare:
+
+```bash
+python zanii_evolve.py --domain acme judge-agreement --labels human.jsonl
+```
+
+It reports raw agreement, Cohen's kappa and per-criterion agreement, weakest first.
+
+**Custom domains.** Anything else is one module, `domains/<name>/adapter.py`,
+exporting a `zanii_evolve.domain.Domain` that runs and scores a harness, renders
+traces for the analyst, and supplies the domain's leakage denylist and guards.
+The core never reads a benchmark format itself.
+
+## Certificates, signing and the registry
+
+```bash
+python zanii_evolve.py --domain acme report --out cert     # cert.json + cert.md
+python zanii_evolve.py verify-report cert.json
+python zanii_evolve.py --domain acme pareto                # score/cost trade-off of every measured harness
+python zanii_evolve.py --domain acme publish               # harness archive + certificate -> registry/
+```
+
+A certificate records the incumbent against H0, the noise band, every accepted
+edit with its hypothesis and measured score and cost change, the outcome of
+every candidate, and every held-out evaluation. It carries a sha256 digest of
+its body, so any edit after issue is detected.
+
+Signing comes in two strengths:
+
+- **HMAC** (`ZANII_EVOLVE_SIGNING_KEY`) proves the issuer to anyone who holds the same key.
+- **Proof-of-action receipt** (`pip install "zanii-evolve[provable]"`) is an Ed25519
+  signature by a `did:key` identity that an owner key delegated `evolve.*` to.
+  Anyone can verify it offline against the owner's public DID, with no shared
+  secret and no network call.
+
+```bash
+python zanii_evolve.py identity --out keys/                 # owner.json (keep offline) + identity.json
+export ZANII_EVOLVE_IDENTITY=keys/identity.json
+python zanii_evolve.py --domain acme report --out cert
+python zanii_evolve.py verify-report cert.json --owner did:key:z6Mk...
+python zanii_evolve.py --domain acme verify-receipts        # no issued certificate removed or altered
+```
+
+Receipts are hash-linked in `runs/<domain>/receipts.jsonl`. Verification without
+`--owner` still checks the signature but reports that the issuer is not pinned,
+because a valid signature alone only proves that *some* key signed.
+
+To optimize for cost instead of score, set `"objective": "cost"` in the domain's
+`zanii_evolve.json` (or pass `--objective cost`). Admissibility is unchanged;
+among the candidates that pass, the cheapest wins. Together with a new
+`ZANII_EVOLVE_POLICY_MODEL` and a fresh `baseline`, this moves a harness to a
+cheaper model without losing quality.
+
+## Memory
+
+The structural `memory` component is `mechanisms.Memory()` in each starting
+harness. It is inert until the proposer wires it in, and it exposes the same
+`write` / `read` / `digest` surface whichever backend runs:
+
+| Backend | When | Storage |
+|---|---|---|
+| ZaniiDB | default when `zaniidb-agent-memory` is installed | `<state_dir>/zaniidb` (SQLite), hybrid BM25 and vector recall |
+| JSONL | ZaniiDB missing, or `ZANII_EVOLVE_MEMORY=jsonl` | locked `*.jsonl` under `<state_dir>` |
+
+Memory is scoped to one run on purpose (`ZANII_DATABASE_URL` is ignored), so
+lessons cannot leak between runs. `mechanisms.TaskMemory` adds a
+recall-before, record-after loop that stores successes as procedures and
+failures as pitfalls. Brief harnesses ship it wired but switched off, so H0 is
+unchanged and the search decides whether it pays.
+
+**Lesson packs** are the explicit, opt-in exception. `lessons export` writes a
+run's general lessons after the leakage guard, a task-id screen, PII redaction
+and de-duplication. `lessons import` merges packs into
+`domains/<name>/shared_lessons.jsonl`, which every trial of that domain then
+starts from, H0 included. A pack switches the domain to the JSONL backend;
+re-run `baseline` after importing one.
+
+The [`skills/zaniidb`](https://github.com/vigilancetrent/zanii-evolve/tree/main/skills/zaniidb)
+and [`skills/zanii`](https://github.com/vigilancetrent/zanii-evolve/tree/main/skills/zanii)
+folders are agent skills that document the ZaniiDB and Zanii SDKs for coding assistants.
+
+## Dashboard and HTTP API
+
+```bash
+python zanii_evolve.py serve                                # http://127.0.0.1:8765/
+ZANII_EVOLVE_API_TOKEN=... python zanii_evolve.py serve     # also enables control endpoints
+```
+
+The dashboard shows the incumbent against H0 and the noise band, every candidate
+with its verdict and diff, the accepted edits and the stored lessons.
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/domains`, `GET /api/domains/<d>` | run summaries, trajectory, candidates |
+| `GET /api/domains/<d>/rounds/<t>/<V>/diff` | a candidate's diff |
+| `GET /api/domains/<d>/memory` | lessons in the run's stores |
+| `GET /api/domains/<d>/pareto` | score/cost frontier |
+| `GET /api/domains/<d>/report` | certificate (the server never signs) |
+| `GET /api/registry` | published harnesses |
+| `POST /api/domains/<d>/start`, `/stop` | run control (token required) |
+| `POST /api/domains` | create a brief domain from a task list (token required, 2 MB limit) |
+
+The server binds to loopback by default and checks the `Host` header. Binding
+any other address requires `ZANII_EVOLVE_API_TOKEN`, which every API request
+must then send as a bearer token, because run data includes diffs and traces.
+
+## Configuration
+
+Hyperparameters live in `domains/<name>/zanii_evolve.json` and can be overridden
+on the command line (`--T`, `--k`, `--m`, `--delta`, `--beta0`, `--beta1`,
+`--objective`, ...). A null `delta` is estimated by `calibrate`.
+
+| Variable | Purpose |
+|---|---|
+| `ZANII_EVOLVE_SEARCH_MODEL` | proposer, analyst and critic model |
+| `ZANII_EVOLVE_POLICY_MODEL`, `ZANII_EVOLVE_JUDGE_MODEL` | brief-domain agent and judge |
+| `ZANII_EVOLVE_SIGNING_KEY` | HMAC key for certificates |
+| `ZANII_EVOLVE_IDENTITY` | identity file for signed receipts |
+| `ZANII_EVOLVE_REGISTRY` | registry location (default `./registry`) |
+| `ZANII_EVOLVE_API_TOKEN` | API control and non-loopback binds |
+| `ZANII_EVOLVE_MEMORY` | `zaniidb` (default) or `jsonl` |
+
+Keep keys in the environment or a secrets manager. `runs/`, `registry/` and
+identity files are ignored by git.
+
+## Command reference
+
+```
+smoke | baseline | calibrate | round | run | status | readjudicate | reevaluate | heldout
+pareto | report | verify-report | verify-receipts | publish | registry | identity
+init-domain | import-tasks | ingest-traces | redteam | judge-agreement | lessons | serve
+```
+
+`python zanii_evolve.py --help` lists every option.
+
+## Project layout
+
+```
+zanii_evolve/          search core: loop, proposer, critic, selection, providers,
+                       brief engine, certificates, registry, API server, dashboard
+zanii_evolve.py        command line
+domains/<name>/        one folder per domain: adapter or tasks, prompts, hyperparameters
+third_party/           starting harnesses (Terminus-2, archipelago), under their own licenses
+skills/                agent skills for the ZaniiDB and Zanii SDKs
+tests/                 offline test suite
+```
+
+## Acknowledgements
+
+Zanii Evolve builds on the RRSI reference implementation (Apache 2.0); see
+[NOTICE](https://github.com/vigilancetrent/zanii-evolve/blob/main/NOTICE). The
+starting harnesses are the Terminus-2 agent from
+[harbor](https://github.com/laude-institute/harbor) and the react_toolbelt agent
+and runner from [archipelago](https://github.com/Mercor-Intelligence/archipelago).
+Evaluation uses [Terminal-Bench](https://github.com/harbor-framework/terminal-bench),
+[SWE-bench Verified](https://github.com/SWE-bench/SWE-bench),
+[Harvey LAB](https://github.com/harveyai/harvey-labs),
+[JobBench](https://github.com/Job-Bench/job-bench-eval),
+[GDPval](https://openai.com/index/gdpval/),
+[APEX-Agents](https://www.mercor.com/apex/apex-agents-leaderboard/),
+[EngDesign](https://github.com/AGI4Engineering/EngDesign) and
+[Frontier-Eng](https://github.com/Einsia/Frontier-Engineering).
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/vigilancetrent/zanii-evolve/blob/main/CONTRIBUTING.md).
+Run `python -m pytest tests` before opening a pull request.
+
+## License
+
+Apache 2.0. See [LICENSE](https://github.com/vigilancetrent/zanii-evolve/blob/main/LICENSE)
+and [NOTICE](https://github.com/vigilancetrent/zanii-evolve/blob/main/NOTICE). Code
+under `third_party/` keeps its own license.