Metadata-Version: 2.4
Name: atlas-upstream
Version: 0.2.0
Summary: Evidence-aware mission planning and recovery for AI agents.
Author: Albert Tan
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.29; extra == "mcp"

# Atlas Upstream

Help an AI agent reach an agreed outcome, recover after interruption and learn from the evidence. Version **0.2.0**, local alpha.

Upstream stores the mission outside the agent's conversation. It chooses a next action using the available facts, each person's authority, access requirements and the cost of asking another question. An agent returning in a new session can recover the current objective, disagreements, active attempts and completion evidence.

## Install and connect an agent

Use Python 3.10 or newer. From the extracted project directory, install the optional MCP integration.

```sh
python3 -m pip install ".[mcp]"
atlas-upstream-mcp --workspace /absolute/path/to/your/project/.upstream
```

Configure your MCP host to launch that executable and those arguments. The directory belongs to this project and should be a local, trusted workspace. The server uses the official MCP Python SDK, with the tested 1.x API. Seven discoverable tools expose their input schemas. A host can read `upstream://guide`, `upstream://example` and `upstream://events` when it needs the operating contract.

| Tool | What an agent can do |
| --- | --- |
| `template` | Describe stages, actions and a success question to obtain a mission specification. |
| `create` | Start a named mission or resume the same specification. |
| `missions` | Discover locally saved missions. |
| `snapshot` | Recover fresh beliefs, disagreements, open attempts and the next decision. |
| `record` | Commit observations and action events in one atomic batch. |
| `history` | Retrieve a page of evidence. |
| `lesson` | Export a verified completion as an Opsbook practice case with explicitly supplied labels. |

For the dependency-free Python core, run `python3 -m pip install .`. The distribution includes a wheel for installation into a separate environment. The `mcp` extra downloads the official SDK and its dependencies. The command-line and JSON-lines interfaces remain available as `atlas-upstream` and `atlas-upstream-jsonl`.

## Try an actual agent-tool exchange

```sh
python3 examples/mcp_client.py
```

An official MCP client discovers the tools, describes a publication task and runs it through a separate server process. The client writes a real file with stale contents. The receiving read detects the mismatch. Upstream requests a repair, requires a successful read, and returns the evidence for completion. A fresh client and server recover that state from disk. The driver follows a written policy. No language model is called.

For the earlier physical and digital demonstrations, use the source checkout.

```sh
python3 demo.py handover
python3 demo.py learning
python3 demo.py bulletin
python3 demo.py compare
python3 -m unittest discover -s tests -v
```

The handover and travel-time exercises simulate physical movement. The bulletin trial uses a real local HTTP server. The paired comparison covers sixteen constructed worlds. [Step through the recordings](Atlas-Upstream-Casebook.html).

## Teach the next session

Use `lesson` after a verified completion, supply the relevant context and name the checks your evidence supports. It returns an Opsbook case, the supporting receipt observations and a digest of the mission journal. Review the exported content and labels, then import the `cases` array into an existing [Atlas Opsbook](https://github.com/Albertito-AI/atlas-opsbook) manual.

```sh
python3 examples/opsbook_bridge.py /path/to/atlas-opsbook/opsbook.py
```

This example imports an observed publication result and three explicitly labelled fixture cases into a temporary manual. Opsbook infers when reader verification applies, checks a separate example and a control, and returns the instruction for a subsequent session. Importing and promoting the result into a working manual is a separate operation.

## Learn the operating contract

[Agent integration](docs/AGENT.md) describes records, retries, concurrency and recovery. [MCP host setup](docs/MCP.md) supplies a configuration fragment and a complete first exchange. [Design](docs/DESIGN.md) explains source authority and selective questions. [Verification](docs/VERIFICATION.md) records what was exercised. [Field exercise](docs/FIELD.md) gives a two-person physical trial.

The host defines the available actions and authenticates reporters. Upstream learns recent action times within a mission and uses designated observations to update its plan. Physical operation requires a person or an adapter capable of observing the actual result. The included physical scenarios have been tested in simulation.
