# Cortex MCP

> **Early-stage work in progress.** Cortex has a functional core scaffold, but
> it is not production-ready. Provider coverage, durable background execution,
> security hardening, and end-to-end validation are still incomplete.

Cortex MCP explores a practical systems problem: how can an agent submit
expensive or long-running AI work once, route it deliberately, inspect its
progress, and retrieve evidence about what happened?

The project is a local-first job broker with MCP and HTTP interfaces. Its design
focuses on reliable orchestration, observable state transitions, cost-aware
routing, provider independence, and human control. Privacy-by-design is an
important boundary throughout the system, but it complements rather than
replaces the broader engineering work.

This public repository contains only source code, documentation, tests, and
synthetic examples. It does not contain private prompts, credentials, household
data, live review artifacts, or deployment configuration.

## What exists today

The Cortex scaffold currently includes:

- job and attempt lifecycle models;
- a SQLite registry using write-ahead logging;
- configurable provider abstractions;
- synchronous fan-out and ordered fallback behavior;
- an Anthropic adapter with message and batch-oriented paths;
- an OpenAI-compatible synchronous adapter;
- conservative pre-submit cost ceilings with fail-closed pricing;
- MCP tools for submission, status, results, cancellation, and briefings;
- a loopback-oriented HTTP surface for submission, status, and briefings; and
- a scheduler entry point that can poll submitted work and dispatch queued jobs.

These components demonstrate the intended architecture. They have not yet been
proven as a dependable unattended service.

## What is not finished

- The native Gemini adapter is a stub.
- OpenAI Batch API support is not implemented.
- Webhook registration and delivery are not implemented.
- Pricing entries must be verified before relying on cost estimates.
- Validation has a bounded first pass; idempotency, crash recovery, richer
  cancellation, and provider provenance need further work.
- The HTTP surface lacks production authentication, authorization, TLS, rate
  limiting, and replay protection.
- No recurring service deployment is included or claimed.
- Cortex does not autonomously modify Home Assistant or any other external
  system.

See the [roadmap](docs/roadmap.md) for the staged plan and
[threat model](docs/threat-model.md) for the current security boundaries.

## Architecture at a glance

```mermaid
flowchart LR
    A["MCP or HTTP caller"] --> B["Cortex broker"]
    B --> C["Cost guard and routing"]
    C --> D["Provider adapter"]
    D --> E["Remote or local model"]
    B <--> F["SQLite job registry"]
    B --> G["JSONL result artifacts"]
    H["Scheduler entry point"] --> B
```

The registry is the system of record for job and attempt metadata. Larger model
outputs are stored as local JSON Lines artifacts. Provider adapters translate a
common job shape into provider-specific calls. MCP and HTTP are alternate
interfaces over the same broker concepts.

The detailed design is documented in
[docs/architecture.md](docs/architecture.md).

## Smart Home Review application

[`applications/smart_home_review`](applications/smart_home_review) is a more
developed experimental application in this repository. It turns a bounded,
read-only subset of Home Assistant configuration, trace summaries, and state
history into a versioned evidence package for later review.

Its public demonstration:

- uses synthetic devices and events;
- has 28 regression tests covering the offline pipeline and collector;
- validates evidence against versioned schemas;
- preserves model agreement and disagreement;
- generates an advisory synthetic report; and
- keeps model submission, scheduling, and autonomous changes disabled.

The live collector has been validated manually and privately, but no live
household evidence belongs in this repository. The application remains
experimental and read-only.

## Local scaffold setup

Python 3.11 or newer is recommended.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp config.example.toml config.toml
```

Review every provider, model, endpoint, price, and data-directory setting in
`config.toml` before running anything. Store API keys only in the environment
variables named by that file. The example intentionally omits cloud prices;
verify and add them before using a cloud target.

To start the MCP process:

```bash
python -m cortex.server
```

To start the optional HTTP scaffold:

```bash
python -m cortex.http_api
```

Keep the HTTP listener on a trusted loopback interface. The current
shared-token requirement is not sufficient protection for an internet-facing
service.

## Run the synthetic application tests

```bash
cd applications/smart_home_review
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v
python -m smart_home_review demo
```

The demo performs no model-provider or Home Assistant network requests.

## Engineering principles

- **Visible state:** job and attempt transitions should be inspectable.
- **Evidence over confidence:** important conclusions should link back to
  structured inputs and explicit validation.
- **Fail closed on cost and privacy:** unknown pricing or unreviewed sensitive
  data should block submission.
- **Provider independence:** orchestration policy should not be tied to one
  model vendor.
- **Human authority:** generated recommendations remain advisory until a person
  reviews and approves them.
- **Honest maturity:** scaffolding, experiments, and production-ready systems
  are labeled differently.

## Documentation

- [Architecture](docs/architecture.md)
- [Threat model](docs/threat-model.md)
- [Testing and validation](docs/testing-and-validation.md)
- [Roadmap](docs/roadmap.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)

## License

Licensed under the [MIT License](LICENSE).