{
  "markdown": "# Archimedes\n\n*Research. Rigor. Proof.*\n\n[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](LICENSE)\n[![Settled on: Arc](https://img.shields.io/badge/settled%20on-Arc-2A4DD1.svg)](https://www.arc.network/)\n\n**Portfolio strategy, under scrutiny.** Archimedes is an agentic strategy generation and\nvalidation system, grounded in research and statistical rigor. You describe what you want\nfrom a portfolio in plain English; it proposes strategies drawn from a corpus of arXiv\nquantitative-finance preprints, and then the part that makes it different — the honest\nvalidation layer — spends its effort trying to reject every one of them: a deflated Sharpe\nratio, a probability of backtest overfitting, a walk-forward out-of-sample pass, and a\nstatic look-ahead audit, with the measured verdict recorded whichever way it lands.\nSurvivors run as paper deployments, so a gated strategy's results play out in the open\nwith full provenance.\n\nLive at **<https://archimedes-arc.com/>**, running against Arc testnet.\n\n## The spine\n\n```\ngenerate  →  rigor-gate  →  execute (paper)  →  explore      (roadmap: vaults → monitor)\n```\n\n**Generate** and **rigor-gate** are the shipped product, and so is **explore** — the\nreasoning traces, the rejected alternatives, the paper provenance behind every proposal.\n**Execute** ships as paper: strategies that survive the gate run as paper deployments —\nthe same decision core a vault will one day use, executing against an append-only paper\ntrade ledger instead of a chain, so results accrue in the open with nothing at stake.\n**Vault execution** and **monitor** are roadmap. The `Vault` / `VaultFactory` contracts are written\nand deployed to Arc testnet, but the deploy-a-vault journey is gated off every public\nsurface behind `ROADMAP_SURFACES_ENABLED`\n([`ui/src/featureFlags.js`](ui/src/featureFlags.js), off by default), and no user vault has\nbeen deployed. When it ships, a strategy that survives the gate will be deployable into a\nnon-custodial vault on Arc, and the agent will rebalance it on a schedule. Today it will\nnot. The locked spine is [`docs/user-stories.md`](docs/user-stories.md).\n\n## Three things to know before anything else\n\n- **Most briefs fail the gate. That is the product working.** A strategy that fails is shown\n  to you with its DSR, PBO and out-of-sample numbers, so you can see exactly why. How many\n  strategies in the curated library currently pass is **unestablished** — the live gate is\n  the only authority on that, and this file will never quote a count.\n- **Research marketplace, not a casino.** Payments are real (USDC on Arc); marketplace\n  settlement is stubbed behind `PAYMENTS_DRY_RUN` pending mainnet. Single-user MVP —\n  multi-user library and social features are roadmap.\n- **Arc testnet only** (chain `5042002`). Faucet USDC comes from\n  <https://faucet.circle.com/> (20 USDC / 2h — on Arc, USDC *is* gas). **No mainnet\n  money.** Generation still settles real testnet USDC — read `GET /api/generate/quote`\n  (prod answers `dry_run: false`). Arc has no mainnet yet; mainnet launch, real-funds\n  custody, and the regulatory architecture are roadmap.\n\n## The rigor gate\n\nThe gate is evidence, not proof. The deflation prices in how many candidates were searched\nbefore this one was picked; the DSR bar is 0.95 — a one-sided 5% test — and it has exactly\none definition in the tree (`DSR_P_BADGE_MIN` in\n`backend/archimedes/services/rigor_profiles.py`, #1794). PBO is computed and disclosed on every passport but does not block the badge while the\nlibrary holds fewer than ten graded strategies — below that, CSCV lacks the power to gate\nhonestly, so it reports `NOT_RUN` with the reason rather than a pass. A check that cannot\nrun says so; it never reports a silent pass.\n\nFull method and thresholds: [`docs/rigor-methods.md`](docs/rigor-methods.md) and\n[`docs/specs/selection-bias-corrections-spec.md`](docs/specs/selection-bias-corrections-spec.md).\nThe papers the gate rests on, including the two cited against us:\n[`docs/cited-literature.md`](docs/cited-literature.md).\n\n## How a strategy gets made\n\nA brief fans out across a regime × mechanism steer grid. Each proposer selects candidate\npapers from the corpus, and fusion turns them into a strategy spec in the internal DSL.\nDeterministic critics then cull the pool with zero LLM calls: provenance and embargo audit,\na real backtest per survivor, and a null check that a candidate must beat buy-and-hold by at\nleast 5 bps net — if none clears it, the run abstains rather than shipping a weak winner. A\ndeterministic synthesizer ranks what is left; only the K=1 winner is persisted, and the\nrejected alternatives are kept and surfaced so you can see what was tried. The externalized\nrigor gate then runs on the winner, outside the debate.\n\nMechanism in full: [`docs/specs/multi-agent-debate-spec.md`](docs/specs/multi-agent-debate-spec.md).\n\n## Quickstart\n\n### The live site\n\n<https://archimedes-arc.com/> runs against Arc testnet. Sign in with email and password,\ndescribe a brief, and read the verdict.\n\n### Run it locally\n\n```bash\ngit clone --recurse-submodules https://github.com/aprin-labs/archimedes.git\ncd archimedes\ncp .env.example .env\n# REQUIRED: generate a local auth secret, then paste it after BETTER_AUTH_SECRET=\npython -c \"import secrets; print(secrets.token_urlsafe(48))\"\ndocker compose up -d --build\n```\n\nThen open <http://localhost:8080>. The backend shares that ingress:\n<http://localhost:8080/health> for the honesty flags, <http://localhost:8080/docs> for the\nAPI. LLM credentials are optional — without one, generation uses the canned fallback.\n\n**[`SETUP.md`](SETUP.md) is the full walkthrough** — prerequisites, platform notes\n(macOS / Linux / WSL2), host tooling for frontend and contract work, and the test suite.\n`make help` lists the dev targets.\n\n### The CLI\n\nThe `archimedes` CLI runs the rigor gate over your own returns series. It is **not on PyPI\nyet**, so install it from this repo:\n\n```bash\nconda env create -f environment.yml   # first time only\nconda activate archimedes\npip install -e ./cli\n```\n\nCheck the install and read the machine-readable contract — no network, no account:\n\n```bash\narchimedes --version        # archimedes, version 0.1.0\narchimedes manifest         # JSON: every command, flag, exit code, and cost class\n```\n\nSign in (Better Auth email + password — no wallet signature), then read your meter and run\nthe gate:\n\n```bash\narchimedes login            # prompts; or set ARCHIMEDES_EMAIL / ARCHIMEDES_PASSWORD\narchimedes meter            # today's generation usage + the live price quote\narchimedes verify returns.csv --trials 40\n```\n\n`returns.csv` is two columns — date and daily return — or `-` to read stdin; a header row is\nskipped automatically. Exit codes are a stable contract, and the split that matters is **`1`\nvs everything else**: `1` means the gate ran and returned a failing verdict, a real answer.\nAny other non-zero means no verdict was produced, so branch on `1` specifically:\n\n```bash\narchimedes verify returns.csv\ncase $? in\n  0) echo \"gate passed\" ;;\n  1) echo \"gate failed, not deploying\"; exit 1 ;;\n  *) echo \"verify did not run\"; exit 2 ;;\nesac\n```\n\nThe codes: `0` passed · `1` gate ran and failed · `2` bad input or no session · `3` not\nimplemented in this release · `4` the gate was reached but not every runnable leg could be\nevaluated. **`4` is a known gap in the published contract** —\n[`cli/src/archimedes_cli/exits.py`](cli/src/archimedes_cli/exits.py) defines it and `verify`\nexits with it, but `archimedes manifest` still publishes only `0`–`3`. The `case` above\nhandles it correctly regardless, because it treats every non-`1` non-zero as \"no verdict\".\n\n`verify` sends only numbers; your strategy code is never uploaded. Two of the gate's four\nchecks cannot run over a bare returns series — PBO needs a trial matrix and the look-ahead\naudit needs strategy source — so both always report `not_evaluable` with a reason, never a\nsilent pass. `archimedes backtest` and `archimedes verify --local` are not implemented yet\nand exit `3`.\n\nFull reference: [`cli/README.md`](cli/README.md) and\n[`skills/archimedes-cli/SKILL.md`](skills/archimedes-cli/SKILL.md).\n\n## Documentation\n\n[`docs/doc-index.md`](docs/doc-index.md) is the register — **a doc not listed there does not\nexist.** The same tree is published, curated, at <https://docs.archimedes-arc.com>.\nThe entry points:\n\n| If you want to… | Read |\n|---|---|\n| Run it locally, including the test suite | [`SETUP.md`](SETUP.md) |\n| Know what the product *is* (the locked spine) | [`docs/user-stories.md`](docs/user-stories.md) |\n| See the architecture map and the stack | [`docs/architecture.md`](docs/architecture.md) |\n| Understand the rigor gate's math | [`docs/rigor-methods.md`](docs/rigor-methods.md) |\n| Read the papers the claims rest on | [`docs/cited-literature.md`](docs/cited-literature.md) |\n| Audit our public claims one by one | [`docs/claims-ledger.md`](docs/claims-ledger.md) |\n| Understand the paper corpus end to end | [`docs/corpus-architecture.md`](docs/corpus-architecture.md) |\n| Drive the whole journey programmatically | [`docs/agent-api.md`](docs/agent-api.md) |\n| Go zero-to-paper-traded as an external agent | [`docs/agent-quickstart.md`](docs/agent-quickstart.md) |\n| Use the command-line tool | [`cli/README.md`](cli/README.md) |\n| Load a grounded agent skill (every claim file:line cited) | [`skills/README.md`](skills/README.md) |\n| Understand Arc / Circle integration | [`docs/arc-integration.md`](docs/arc-integration.md) |\n| Operate the live stack | [`docs/runbooks/operations.md`](docs/runbooks/operations.md) |\n| Browse every design + planning doc | [`docs/doc-index.md`](docs/doc-index.md) |\n| Add a doc without misfiling it | [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) |\n| Write a test the way this repo wants | [`docs/testing-conventions.md`](docs/testing-conventions.md) |\n| Know who owns what | [`docs/team.md`](docs/team.md) |\n| Get context for a Claude Code session | [`CLAUDE.md`](CLAUDE.md) |\n\n**Live numbers come from the live system, never from this file.** Contract census is\n`GET /api/config/contracts`, honesty flags are `GET /health`, and the test count is\n`pytest --collect-only -q | tail -1`. This file quotes no counts that a reader cannot\nre-derive from one of those.\n\n## Known limitations (Arc testnet)\n\n- **The corpus is arXiv preprints, not peer-reviewed papers**, and it holds metadata and\n  abstracts only — the row count `/health` publishes as `corpus_papers` is a manifest\n  import, not a measure of anything analysed. Do not freeze that count in prose; the\n  corpus probe can timeout. Candidate selection over it is a **keyword\n  filter**. Only that already-selected candidate set is then re-scored, at request time,\n  across title and abstract — by `all-MiniLM-L6-v2` when that model is loaded in-process, by\n  lexical TF-IDF when it is not. Nothing is precomputed: the `papers` schema carries title\n  and abstract text and no vector column, so no index is built ahead of the request.\n  `/health` names the scorer that is actually live in `paper_rag` and `paper_rag_reason`,\n  publishes `corpus_embedded_at_rest: false` for the corpus itself, and publishes\n  `rerank_candidate_cap` because only that many candidates reach the model. Read those\n  fields rather than this line. Tracked in\n  [#778](https://github.com/aprin-labs/archimedes/issues/778) and\n  [#1488](https://github.com/aprin-labs/archimedes/issues/1488).\n- **The knowledge graph is not built.** No KB artifact has ever been produced, so `/health`\n  reports `corpus_kg_built: false` with zero entities and zero relations,\n  `GET /api/corpus/graph` refuses with **503 `kb_artifact_not_found`** instead of\n  synthesizing a graph, and `GET /api/corpus/kg/*` returns empty entity and relation sets.\n  Citation-link extraction over the corpus is roadmap. Tracked in\n  [#778](https://github.com/aprin-labs/archimedes/issues/778).\n- **Vault execution is not shipped**, per the spine above. The contracts are deployed and\n  the routes exist, but the journey is flag-gated off every public surface and no user vault\n  has been deployed.\n- **AMM pools are thinly funded**, so many swaps are not executable. The agent's liquidity\n  guard skips empty pools and logs the reason instead of routing capital into a doomed trade\n  — see [`docs/arc-integration.md`](docs/arc-integration.md).\n- **Not every reasoning trace is anchored on-chain.** The agent writes a trace for every\n  decision it reaches, including a `skip`, and a decision that produced no transaction has\n  no hash to verify. Read `GET /api/traces/` and check `arc_tx_hash` before treating a trace\n  as anchored.\n\nEvery public claim this repo makes, with a per-claim verdict and the `file:line` that backs\nit, is tracked in [`docs/claims-ledger.md`](docs/claims-ledger.md).\n\n## Contributing\n\nFork, branch, PR to `main`. The branch model in one paragraph:\n\n- **`main` is the only long-lived branch, and it is the deploy branch** — every merge builds\n  and deploys to the live stack. There is no `develop`. `main` moves continuously; branch\n  late, rebase right before merging, and merge in a tight window.\n- Short-lived per-owner branches, `<your-handle>/<short-name>` → PR → merge → delete.\n- **Merge commits only.** Squash- and rebase-merge are disabled in repo settings; use\n  `gh pr merge <n> --merge`.\n- **Close the issue from the PR body with a real keyword** — `Closes #123` / `Fixes #123` /\n  `Resolves #123`, the keyword immediately before each `#`, repeated once per issue\n  (`Closes #1 and #2` closes only #1). Use `Part of #123` for a deliberate non-closing\n  reference. [`.github/pull_request_template.md`](.github/pull_request_template.md) prompts\n  for it.\n- One logical change per PR. Never force-push `main`. Never commit secrets or `.env`.\n  Force-pushing your *own* unmerged branch is fine and expected.\n\nFull conventions — review rules, CI gates, commit style —\nare in [`CLAUDE.md`](CLAUDE.md); testing conventions are in\n[`docs/testing-conventions.md`](docs/testing-conventions.md) and doc conventions in\n[`docs/CONVENTIONS.md`](docs/CONVENTIONS.md).\n\n## License\n\n[Unlicense](LICENSE) — full public-domain dedication. Use, modify, distribute freely. No\nwarranty.\n",
  "bytes": 14248,
  "sha": "ec7c5960bf601b20d0617086c6079d2adecf9ea538563fa358a92fc07dff6c20",
  "repo_slug": "aprin-labs/archimedes",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_aprin_labs_archimedes_openwiki_index_md_65c7d794/readme"
}