master-agents-client 1.0.1

Thin client for the Master Agents service. Talks to a hosted server; bundles no orchestration logic, prompts, or agent specs.

Master Agents — Client

master-agents-client is the public client wheel for Master Agents, a vendor-agnostic agent orchestration framework with a designed pipeline, deterministic traces, and cost gating built into every model call.

pip install master-agents-client

Requires Python 3.11+.

---

For developers building agent pipelines

Master Agents is opinionated about three things most frameworks treat as afterthoughts:

1. Cost is a first-class correctness constraint

Every pipeline runs through estimate_tokens gating before a model call fires. cost_budget caps are per-pipeline — when a pipeline blows its budget, it halts before the next over-budget call, not after. Repeated runs benefit from byte-stable prefix caching (typical hit rates 70–90% on DeepSeek / Anthropic providers), so the second run of a pipeline costs a fraction of the first.

Set a budget. Forget about it.

2. Trace is truth. Replay is proof.

Every session emits a structured JSONL trace. Replay the trace against the same model config to reproduce the run path — deterministic where reachable, with non-determinism captured and surfaced where it exists. CI can assert that a specific pipeline still produces the same review verdict on the same input.

Don't log. Replay.

3. Agents should be auditable, not magical

The pipeline DAG (kind: graph) is declared in code and inspectable end to end: brainstorm → architect → plan → code → review → aggregate. No hidden subagents, no emergent topology, no "the LLM figured it out." You can render the graph before running it.

Show the graph. Hide the magic.

---

What the client gives you

• A CLI (mao-client) to drive a hosted Master Agents service from a workstation: one-shot runs, interactive chat, login/logout, detach + resume.
• Tool inversion: file / git / bash / RAG operations execute on your machine under explicit path allowlists declared at login. Source files never leave the local environment — only tool output text travels to the service.
• Trace streaming over WebSocket; persistent server-side sessions that survive laptop close, network blips, and cross-machine resume.

The client itself ships no orchestration logic, no prompts, no agent specs — those live on the service. Upgrades happen server-side; the client stays a stable terminal.

---

First chat (60 seconds)

# 1. Save server URL + token (paste at the prompt or via --token).
mao-client remote login --server https://your-master-agents-service.example

# 2. Start an interactive session.
mao-client remote chat

# 3. Or run a one-shot prompt against a specific master agent.
mao-client remote run -m brainstormer "What should I prototype this week?"

Inside chat, /help lists all slash commands (model switching, cost caps, session controls, etc.).

---

Why not LangChain / LangGraph / CrewAI / AutoGen / OpenAI Assistants / Claude Agent SDK?

Three concrete reasons that don't depend on framework taste:

Concern	What other frameworks give you	What Master Agents gives you
Cost predictability	Logging / monitoring tools — you find out after the run	estimate_tokens gate + cost_budget cap per pipeline; halt before an over-budget call
Reproducibility	Re-run and hope the model samples the same way	Replay against the captured JSONL trace; deterministic where reachable
Topology	Emergent agent-to-agent conversations decided at runtime	DAG declared upfront; render the graph before running it

You can run the same pipeline against multiple providers (DeepSeek by default, with Anthropic / OpenAI / OpenRouter as drop-in alternatives) and compare outputs — model swaps are a config change, not a code change.

---

Sessions, detach, resume

Sessions are first-class identities, not keepalive. Detach a long-running pipeline mid-flight, reconnect from a different machine an hour later, continue from the exact server-side state:

mao-client remote run --detach -m parallel_coder "<long-running brief>"
# ... close laptop, commute, etc.

mao-client remote chat --resume     # picks up the most recent session
mao-client remote chat --pick       # interactive list of detached sessions

---

What runs where

	Where it runs
Chat REPL, slash commands	Your machine (this client)
File reads / writes / edits, bash, git	Your machine (this client)
Agent reasoning, model calls, retrieval, DAG execution	The service

The client never uploads your source files. Only the tool output text the agent asked for travels to the service.

---

Configuration

Server URL + token live in ~/.master_agents/remote.yaml after login. Override per-call with --config <path>. Env-var override: MASTER_AGENTS_REMOTE_CONFIG=/path/to/remote.yaml.

---

Self-host (the orchestration server)

The hosted service is master-agents (a separate package, deliberately not on PyPI — it carries the agent specs, framework internals, RAG configs, and prompts). Self-host via authenticated git access:

pip install "git+ssh://[e-mail]/<owner>/master_agents_os.git#subdirectory=packages/py"
mao-server serve --http --host 0.0.0.0 --port 8000

That gates per-person on repo access — the right authorisation model for IP-bearing code, not anonymous PyPI.

---

Links

• Slash command + troubleshooting reference: USER_GUIDE.md
• Architecture overview: docs/MASTER_ARCHITECTURE.md (upstream repo)
• Versioning policy: docs/VERSIONING.md (upstream repo)
• Release runbook: docs/RELEASE.md (upstream repo)

---

License

MIT. The server-side master-agents package is proprietary; this client wheel is permissively licensed so anyone can integrate against a hosted service.