# template_sia

Public exemplar for the SIA (Self-Improvement Agent) harness: Meta → Target → Feedback
loops with public/private task splits and canonical generation artifacts.

## When to use this template

Use this template when you need a **self-improvement-agent evaluation
harness**: Meta → Target → Feedback generation loops, public/private task
splits to detect overfitting, deterministic fixture replay for testability,
and fail-closed loop validation. It demonstrates the harness *mechanics* —
not autonomous live code modification (see the honesty note below). For
agent-team coordination mechanisms see
[`template_autoscientists`](../template_autoscientists/); for a bounded
AutoResearch loop see
[`template_autoresearch_project`](../template_autoresearch_project/). Full
roster:
[`projects/AGENTS.md`](../../AGENTS.md#permanent-canonical-exemplars).

## Publication and rendering

The publishing metadata and per-platform status below are **compiled from
`manuscript/config.yaml`** by `infrastructure.publishing.status_report` — do not
hand-edit between the markers; update the config and regenerate (see the legend).

<!-- PUBLISHING-STATUS:START (generated by infrastructure.publishing.status_report) -->
**Self-Improvement Agent Harness: A Deterministic SIA Exemplar** · v0.1.2 · MIT · Daniel Ari Friedman

Concept DOI: [10.5281/zenodo.20453879](https://doi.org/10.5281/zenodo.20453879) | Version DOI: [10.5281/zenodo.20932066](https://zenodo.org/records/20932066) | Repository: [docxology/template_sia](https://github.com/docxology/template_sia)

Publishing surface — 20 platforms, 9 published:

| Platform | Tier | Status | Reference | Credentials |
| --- | --- | --- | --- | --- |
| zenodo | first-class | ✅ published | [10.5281/zenodo.20453879](https://doi.org/10.5281/zenodo.20453879) | `ZENODO_API_TOKEN` |
| github | first-class | ✅ published | [docxology/template_sia](https://github.com/docxology/template_sia) | `GITHUB_TOKEN` |
| arxiv | first-class | ⚪ available | — | — |
| pypi | first-class | ✅ published | [https://test.pypi.org/project/template-sia/0.1.2/](https://test.pypi.org/project/template-sia/0.1.2/) | `PYPI_TOKEN`, `TESTPYPI_TOKEN` |
| ipfs_pinata | first-class | ✅ published | [https://gateway.pinata.cloud/ipfs/QmccbCX9YXJMd3fNfkZ3H59dnWRnB6xgeVCM8kmPGQtaBh](https://gateway.pinata.cloud/ipfs/QmccbCX9YXJMd3fNfkZ3H59dnWRnB6xgeVCM8kmPGQtaBh) | `PINATA_JWT` |
| ipfs_web3storage | first-class | ⚪ available | — | `WEB3_STORAGE_TOKEN` |
| software_heritage | first-class | ✅ published | [https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/docxology/template_sia](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/docxology/template_sia) | — |
| github_pages | first-class | ✅ published | [https://docxology.github.io/template_sia/](https://docxology.github.io/template_sia/) | `GITHUB_TOKEN` |
| cloudflare_pages | first-class | ⚪ available | — | `CLOUDFLARE_API_TOKEN` |
| netlify | first-class | ✅ published | [https://6a4442bb57aaff1e1b2992d1--tranquil-kleicha-0c9203.netlify.app](https://6a4442bb57aaff1e1b2992d1--tranquil-kleicha-0c9203.netlify.app) | `NETLIFY_AUTH_TOKEN` |
| huggingface_hub | first-class | ✅ published | [https://huggingface.co/datasets/ActiveInference/template_sia](https://huggingface.co/datasets/ActiveInference/template_sia) | `HUGGINGFACE_TOKEN`, `HF_TOKEN` |
| osf | first-class | ✅ published | [https://osf.io/85bxe/](https://osf.io/85bxe/) | `OSF_TOKEN` |
| amazon_kdp | documented | 🟡 planned | — | `AMAZON_KDP_EMAIL`, `AMAZON_KDP_PASSWORD` |
| google_play_books | documented | 🟡 planned | — | `GOOGLE_PLAY_BOOKS_SERVICE_ACCOUNT_JSON` |
| gumroad | documented | 🟡 planned | — | `GUMROAD_ACCESS_TOKEN` |
| leanpub | documented | 🟡 planned | — | `LEANPUB_API_KEY` |
| lulu | documented | 🟡 planned | — | `LULU_CLIENT_KEY`, `LULU_CLIENT_SECRET` |
| draft2digital | documented | 🟡 planned | — | `DRAFT2DIGITAL_API_TOKEN` |
| stripe | documented | 🟡 planned | — | `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY` |
| ingramspark | documented | 🟡 planned | — | `INGRAMSPARK_CLIENT_ID`, `INGRAMSPARK_CLIENT_SECRET` |

_Keywords: self-improvement agents, benchmark harness, reproducible research, agent evaluation._

_Status legend: ✅ published (durable identifier recorded in `config.yaml`) · 🔵 reserved (identifier reserved but not yet registered by final publication) · ⚪ available (adapter implemented and locally verifiable) · 🟡 planned. This block is generated — edit `manuscript/config.yaml`, then regenerate with `uv run python -m infrastructure.publishing.status_report --project <path> --write`._
<!-- PUBLISHING-STATUS:END -->

The 3 platforms still shown ⚪ available are not automatable to "published" with
current tooling/credentials, not an oversight: **arXiv** has no submission API
in this codebase (`infrastructure.publishing.arxiv` only prepares a local
tarball — a human must upload it via arxiv.org and the resulting `arxiv` URL
would then be added to `publication.published_artifacts`); **Cloudflare
Pages** needs a `CLOUDFLARE_ACCOUNT_ID` the configured API token cannot
auto-discover; **IPFS (Web3.Storage)** has no `WEB3_STORAGE_TOKEN` configured.

- Canonical renderer: [docxology/template](https://github.com/docxology/template) with `--project templates/template_sia`
- Tracked outputs: [`output/`](output/) in this project and `output/templates/template_sia/` in the monorepo; public output files above 50 MB stay out of git.

To regenerate this exemplar from the public monorepo:

```bash
git clone https://github.com/docxology/template
cd template
uv sync
./run.sh --project templates/template_sia --pipeline --core-only
uv run python scripts/pipeline/stage_04_validate.py --project templates/template_sia
uv run python scripts/pipeline/stage_05_copy.py --project templates/template_sia
```

Standalone repositories are publication mirrors for source, DOI metadata, and
tracked rendered artifacts. Use the monorepo above when you need the full shared
infrastructure, pipeline stages, or cross-template validation.

## Quick start

```bash
uv run python projects/templates/template_sia/scripts/run_sia_loop.py
uv run python projects/templates/template_sia/scripts/z_generate_manuscript_variables.py
uv run python scripts/pipeline/stage_01_test.py --project templates/template_sia --project-only
```

Default runs replay fixtures under `src/fixtures/recorded_generations/`. Pass
`--live-sia` for bounded subprocess execution.
The reusable Layer-2 adapter is `src/loop.py`; `scripts/run_sia_loop.py` is a
thin CLI that parses flags, calls that adapter, and prints artifact paths.

> **Live mode is a deterministic stub.** `--live-sia` runs the *reference* agent
> as a bounded subprocess and records its evaluation, but it does **not** mutate
> target code and uses **no sandbox**: the `improvement.md` feedback note is
> illustrative and is never applied, so the target agent is identical across
> generations. Fixture replay contains genuinely executed threshold variants,
> but this toy dataset's separation gap makes all three score 1.0; the flat
> trace is a robustness control, not evidence of improvement. This exemplar
> shows harness mechanics, not autonomous live code modification.

## Documentation

- [`AGENTS.md`](AGENTS.md) — module map and contracts
- [`docs/quickstart.md`](docs/quickstart.md) — fork and extend
- [`../../../infrastructure/sia/README.md`](../../../infrastructure/sia/README.md) — Layer 1 API

## Template integrity

- Forward backlog: [`TODO.md`](TODO.md).
- Copy-and-customize config: [`manuscript/config.yaml.example`](manuscript/config.yaml.example).
- Project validation: `uv run pytest projects/templates/template_sia/tests/ --cov=projects/templates/template_sia/src --cov-fail-under=90`.
- Repo drift validation: `uv run python scripts/audit/check_template_drift.py --strict`.

<!-- foam-orphan-nav:start (hand-maintained: links sub-docs so they are reachable; no generator refreshes or validates this block) -->

## Directory & sub-document map

Navigation links to in-tree documents (keeps them discoverable):

- [scripts/ — template_sia](scripts/AGENTS.md)
- [Scripts — template_sia](scripts/README.md)
- [src/ — template_sia](src/AGENTS.md)
- [Source — template_sia](src/README.md)
- [src/figures/](src/figures/AGENTS.md)
- [Figures — template_sia](src/figures/README.md)
- [src/fixtures/](src/fixtures/AGENTS.md)
- [Fixtures — template_sia](src/fixtures/README.md)
- [Improvement gen 2](src/fixtures/recorded_generations/gen_2/improvement.md)
- [Improvement gen 3](src/fixtures/recorded_generations/gen_3/improvement.md)
- [tasks/](tasks/AGENTS.md)
- [Tasks — template_sia](tasks/README.md)
- [mini_classify](tasks/mini_classify/README.md)
- [tasks/mini_classify/data/](tasks/mini_classify/data/AGENTS.md)
- [Task data — mini_classify](tasks/mini_classify/data/README.md)
- [data/private/](tasks/mini_classify/data/private/AGENTS.md)
- [Private task data](tasks/mini_classify/data/private/README.md)
- [data/public/](tasks/mini_classify/data/public/AGENTS.md)
- [Public task data](tasks/mini_classify/data/public/README.md)
- [Mini classify task](tasks/mini_classify/data/public/task.md)
- [reference/](tasks/mini_classify/reference/AGENTS.md)
- [Reference agent](tasks/mini_classify/reference/README.md)
- [tests/ — template_sia](tests/AGENTS.md)
- [Tests — template_sia](tests/README.md)

<!-- foam-orphan-nav:end -->