Metadata-Version: 2.5
Name: merced-ai
Version: 0.4.0
Summary: An OAP-native broker for existing AI agent harnesses.
Project-URL: Homepage, https://github.com/AlexMercedCoder/merced-ai
Project-URL: Repository, https://github.com/AlexMercedCoder/merced-ai
Project-URL: Issues, https://github.com/AlexMercedCoder/merced-ai/issues
Author: Alex Merced
License: Apache-2.0
License-File: LICENSE
Keywords: acp,agents,automation,cli,codex,oap
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: agentic-graph-spec<2,>=1.0.1
Requires-Dist: open-agent-profile<2,>=1.0.1
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rich<15,>=13.9
Requires-Dist: typer<1,>=0.12.5
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: fastapi<1,>=0.115; extra == 'dev'
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: playwright<2,>=1.50; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Requires-Dist: uvicorn<1,>=0.30; extra == 'dev'
Provides-Extra: webui
Requires-Dist: fastapi<1,>=0.115; extra == 'webui'
Requires-Dist: uvicorn<1,>=0.30; extra == 'webui'
Description-Content-Type: text/markdown

# Merced AI

Merced AI is a local-first broker for AI agent harnesses already installed on your machine. It
discovers those harnesses, normalizes their noninteractive interfaces, and uses Open Agent Profile
(OAP) documents to create portable bots you can chat and collaborate with.

Merced AI is deliberately not another agent loop. The selected harness still owns model access,
tools, authentication, sandboxing, approvals, and final policy enforcement.

## MVP capabilities

- Safe executable and version discovery for 14 harnesses, including Codex, Claude Code, Gemini CLI,
  OpenCode, Goose, Loro, MagAgent, DSH, Pi, Prime Agent, OpenClaw, and Kimi Code CLI.
- Reference OAP validation, digest calculation, profile discovery, and minimal profile authoring.
- Read-only AGS 1.0 validation and deterministic planning with digests, dependency order,
  reachability, worst-case execution bounds, cost/tier summaries, and explicit unsupported features.
- Project-local and user-global bot bindings with preferred and fallback harnesses.
- Honest native, projected, degraded, and unsupported profile projection reports.
- One-shot bot runs, multi-turn local chat, and attributed multi-bot group conversations.
- Durable, atomic project-local conversation sessions with resume support.
- Machine-readable JSON output for inventory, profiles, bots, dry runs, and results.
- Bounded subprocess execution without a shell, with timeout and Ctrl+C cancellation.

## Installation

```bash
python -m pip install merced-ai
# optional UI
python -m pip install 'merced-ai[webui]'
```

For development:

```bash
python -m pip install -e '.[dev]'
merced-ai --version
```

Python 3.11 or newer is required. At least one supported harness must be installed and authenticated
for a real run. Inventory and dry-run workflows do not require model access.

See the [installation guide](docs/INSTALLATION.md) for pipx/uv, platform-specific discovery, and
explicit executable overrides.

## Quick start

Initialize a workspace:

```bash
merced-ai init
merced-ai harness list
```

Create a minimal OAP profile:

```bash
merced-ai profile create reviewer \
  --description "Reviews code for concrete defects before merge." \
  --instructions "Review code. Report verified defects and do not edit files."
```

Bind it to a harness:

```bash
merced-ai bot create reviewer \
  --profile reviewer \
  --harness codex \
  --fallback claude
```

Review the exact projection without launching a model:

```bash
merced-ai ask reviewer "Review the current diff" --dry-run --explain
merced-ai profile effective reviewer --harness codex
```

Run or chat:

```bash
merced-ai ask reviewer "Review the current diff"
merced-ai chat reviewer
merced-ai group chat reviewer builder tester
merced-ai group ask reviewer builder tester --prompt "Give independent assessments" --json
merced-ai session list
merced-ai session resume <session-id>
```

Launch the optional local UI:

```bash
python -m pip install 'merced-ai[webui]'
merced-ai ui
```

The UI binds to loopback and exchanges an ephemeral fragment token for an HTTP-only local session.
It uses the same profile, bot, routing, projection, session, and harness services as the CLI. You
can create profiles and bots, create single or group conversations, target `@mentioned` bots or ask
everyone concurrently, choose routes, approve or cancel runs, inspect authority and harness health,
and search/resume/export attributed transcripts. Group setup has searchable ordered selection,
progressive per-bot status, exact failed-bot retry, `@mention` completion, stable identities,
conversation naming, and derived participant sets. Workspace data renders before executable
probing; cached harness health then refreshes progressively in the background. The composer can
attach bounded project files and browser uploads, recent durable run records show context/events/
duration/partial failures, completion notifications are opt-in, and each active route exposes a
copyable native-harness handoff command. See the
[UI guide](docs/UI.md) and
[group-chat guide](docs/GROUP_CHAT.md) for the security, dispatch, and streaming boundaries.

![Merced AI desktop group conversation](docs/screenshots/merced-ai-group-desktop.jpg)

The layout is responsive down to a compact mobile collaboration view. See the
[mobile group-chat screenshot](docs/screenshots/merced-ai-group-mobile.jpg).

Use `-C PATH` on project-aware commands to select another workspace. Use `--json` on read and
one-shot commands for automation.

## Standards support

Merced AI `0.4.0` uses `open-agent-profile>=1.0.1,<2` and
`agentic-graph-spec>=1.0.1,<2`. It claims OAP 1.0 Level 1 as a broker and AGS 1.0 Level 0 as a
read-only parser/planner. Merced AI does not execute AGS graphs, apply OAP state deltas, or replace
the selected harness's final policy enforcement. See the [OAP conformance result](docs/oap-conformance.json),
[AGS conformance result](docs/ags-conformance.json), and [Agentic Graph guide](docs/AGENTIC_GRAPHS.md)
for the pinned revisions and exact boundary.

## Harness matrix

| Harness | Discovery | Execution | OAP projection |
| --- | --- | --- | --- |
| MagAgent | yes | native one-shot | native for project-discovered profiles |
| Loro | yes | native one-shot | native for project-discovered profiles |
| Claude Code | yes | structured print mode | system-prompt projection |
| Codex | yes | noninteractive exec | delimited prompt compatibility mode |
| Gemini CLI | yes | structured headless mode | delimited prompt compatibility mode |
| OpenCode | yes | structured run mode | delimited prompt compatibility mode |
| Goose | yes | structured run mode | system-prompt projection |
| Anton | yes | stdin REPL bridge | delimited prompt compatibility mode |
| DeepSeek Harness (DSH) | yes | headless profile | delimited prompt compatibility mode |
| Antigravity CLI (AGY) | yes | structured print mode | delimited prompt compatibility mode |
| Pi Coding Agent | yes | structured print mode | system-prompt projection |
| Prime Agent | yes | structured print mode | system-prompt projection |
| OpenClaw | yes | embedded local agent | delimited prompt compatibility mode |
| Kimi Code CLI | yes | read-only print mode | delimited prompt compatibility mode |

"Native" means the harness receives the OAP profile name through its own CLI. It does not mean
Merced AI can supersede harness policy. Projection labels describe Merced AI's broker behavior, not
certification of a selected harness's effective runtime. Native handoff remains bounded by that
harness's own policy and diagnostics.

GLM is treated as a model-family route, not a separate harness. Use it through a supported host
such as Claude Code, OpenCode, Goose, Pi, or Prime Agent. Kimi models can likewise be selected in
multi-provider harnesses, while the dedicated Kimi Code CLI has its own adapter. See
[COMPATIBILITY.md](docs/COMPATIBILITY.md) for qualification status and caveats.

DSH can use a non-DeepSeek provider through its bundled `llm-pi-ai` settings. Kimi can use a
custom config selected with `MERCED_AI_KIMI_CONFIG_FILE`; standard provider environment variables
remain outside Merced AI. See the compatibility guide for a key-free DSH example and current live
qualification results.

## Storage

Project-local data:

```text
.agents/                    OAP profiles
.merced-ai/bots/            bot bindings
.merced-ai/sessions/        normalized conversation sessions
```

User-global data defaults to `~/.config/merced-ai` on Linux and follows the platform configuration
directory on Windows. Set `MERCED_AI_HOME` to override it for automation or tests.

OAP profiles remain the authoritative source for identity and learned state. Session JSON files do
not replace profile state.

## Security posture

- Harness discovery never installs packages or scans the full filesystem.
- Child commands are passed as argument arrays with `shell=False`.
- Plaintext credentials are rejected by the OAP reference validator.
- Harness policies remain authoritative.
- Degraded profile injection is clearly reported and delimited.
- Runs time out, captured output is bounded, and cancellation terminates the child process.
- Automatic fallback happens only when a harness is unavailable, never after a paid or mutating run
  has begun.

See [PRD.md](PRD.md) for the full product requirements, security model, architecture, and roadmap.
The [documentation index](docs/README.md) links configuration, detection, troubleshooting,
architecture, validation, and release guides.

## Development

```bash
ruff format --check .
ruff check .
pytest
python -m build
```

Unit and CLI tests use isolated filesystems and mocked harness processes. They do not call models or
require network access.
