Metadata-Version: 2.4
Name: midcenturion
Version: 0.1.0
Summary: Local, resumable research investigations with executable validation gates
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp==1.30.0

# Midcenturion

Local MCP tools and a portable skill for recursive, evidence-backed research. Start with a question in your existing agent. The agent searches, reasons and proposes alternatives; Midcenturion saves the investigation and enforces versioned validation gates.

The web prototype is an earlier interaction study. It is not needed to use the runtime.

## Local setup

Requires Python 3.11 or later. From this folder:

```sh
python3 scripts/install_local.py
```

The installer creates an isolated runtime under `~/.local/share/midcenturion/runtime`, a `~/.local/bin/midcenturion` launcher, and a copied user skill. It reports the exact MCP registration command; it does not modify unrelated client settings. To register in Codex:

```sh
codex mcp add midcenturion -- "$HOME/.local/bin/midcenturion" serve
```

Start a fresh agent session and ask:

> Use $midcenturion to investigate whether a Rust rewrite would improve this app, or whether a different system/data design would help more. Retain competing explanations and identify the smallest useful test.

Other local MCP clients can launch the same executable with `serve` as its only argument, over stdio. Copy `skills/midcenturion` into the client's supported skill directory when it supports skills. The package needs no model API key; the caller supplies model and research tools.

## Runtime and state

- `midcenturion doctor` shows the installed runtime, store and evaluators.
- `midcenturion call list` lists saved investigations.
- `midcenturion call inspect --json '{"investigation_id":"…"}'` resumes one.
- `midcenturion call <operation> --json-file input.json` runs the same operations as MCP. `--json-file -` reads stdin.
- `MIDCENTURION_HOME` selects an isolated state directory. Default: `~/.local/share/midcenturion/state` (or the equivalent under `XDG_DATA_HOME`).

See [the skill](skills/midcenturion/SKILL.md) and [tool contract](skills/midcenturion/references/tools.md) for the research loop and argument examples.

SQLite owns revisions and atomic acceptance. Content-addressed artifacts preserve exact input and result identity. Same-input retries reuse their request identity; conflicting request reuse or stale writes fail. Closing the agent stops research; a fresh caller can resume saved work. There is no background worker.

## What validation establishes

`quote_anchor` checks a literal quote in a caller-supplied source snapshot. It does not prove authentic retrieval, entailment or truth. `json_assertions` checks submitted structured values, not the execution that allegedly produced them. `revision_fixture` actually executes one of the installed controlled algorithms and compares its outputs to fixed expectations; it is not a production benchmark. Further evaluators can be explicitly installed as trusted Python entry points in `midcenturion.evaluators`.

An attributed review is a recorded judgment. Acceptance requires matching current check receipts and, by default, a supported review. The accepted conclusion must match the checked candidate's statement exactly; changing its wording requires a new revision and checks. Acceptance establishes compliance with that case's chosen criteria, not universal truth, exhaustive discovery, or global optimality. The recorded-action budget does not meter the caller's model/search spend or impose a wall-time limit on trusted plug-ins.

The runtime exposes no arbitrary shell execution, automatic source fetching, CRM writing, or hosted service. All local callers configured for a store share access to that store; this is not a multi-tenant security boundary.

## Development checks

```sh
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python -m unittest discover -s tests -v
```

The MCP adapter pins the maintained v1 SDK for compatibility with existing stdio clients. Protocol integration tests use a real spawned server, including a fresh server process for resume.
