Metadata-Version: 2.4
Name: master-agents-client
Version: 3.14.0
Summary: Thin client for the Master Agents service. Talks to a hosted server; bundles no orchestration logic, prompts, or agent specs.
Author: Thang Nguyen
License: MIT
Project-URL: Homepage, https://agents.sim-os.ai
Project-URL: Issues, https://github.com/nguyenhoangthangbt/master-agents-client/issues
Keywords: agents,llm,ai,client,cli
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: office
Requires-Dist: python-docx>=1.1; extra == "office"
Requires-Dist: python-pptx>=0.6.23; extra == "office"
Requires-Dist: openpyxl>=3.1; extra == "office"
Requires-Dist: Pillow>=10; extra == "office"
Provides-Extra: pdf
Requires-Dist: pypdf<7,>=4.0; extra == "pdf"
Requires-Dist: xhtml2pdf>=0.2.16; extra == "pdf"
Provides-Extra: charts
Requires-Dist: matplotlib>=3.8; extra == "charts"
Provides-Extra: web
Requires-Dist: beautifulsoup4>=4.12; extra == "web"
Provides-Extra: jsonpath
Requires-Dist: jsonpath-ng>=1.5; extra == "jsonpath"
Provides-Extra: full
Requires-Dist: python-docx>=1.1; extra == "full"
Requires-Dist: python-pptx>=0.6.23; extra == "full"
Requires-Dist: openpyxl>=3.1; extra == "full"
Requires-Dist: Pillow>=10; extra == "full"
Requires-Dist: pypdf<7,>=4.0; extra == "full"
Requires-Dist: xhtml2pdf>=0.2.16; extra == "full"
Requires-Dist: matplotlib>=3.8; extra == "full"
Requires-Dist: beautifulsoup4>=4.12; extra == "full"
Requires-Dist: jsonpath-ng>=1.5; extra == "full"
Dynamic: license-file

# 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.

```bash
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 awareness, not just reporting

Every agent's system prompt carries a `<runtime_limits>` block at runtime
listing its own per-turn caps: output budget (tokens), max steps, max
total steps, and the wall-clock timeout per local-tool call. Agents read
those caps and plan within them — when a brief exceeds capacity, the
agent refuses upfront and proposes splitting it, instead of producing
truncated work that hits the cap mid-thought.

Layered on top:

- **`estimate_tokens` tool** — agents can probe a path's token cost
  before reading. Results classify into a tier ladder (tier_1 ≤ 100k
  silent; tier_2 100–200k asks the user; tier_3 > 200k auto-rejected,
  agent must narrow scope).
- **Per-spec `cost_budget`** — opt-in YAML field on agent specs.
  When set, the runtime enforces hard per-step pre-call abort when
  cumulative spend would breach the cap. Pick the spec that matches
  your risk tolerance.
- **Byte-stable prefixes by design** — agent system prompts are kept
  byte-identical across turns within a session, so the model layer's
  prefix caching maximises cache hits on repeat runs (second runs of
  the same pipeline cost a fraction of the first).

> *Show the cap. Plan within it.*

### 2. Trace is truth

Every session emits a structured JSONL trace — every tool call, every
model response, every cost event. CI can diff traces across runs to
detect regressions; post-mortems use the trace as the single source of
truth instead of stitching logs together from multiple places.

> *Don't log. Trace.*

### 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)

```bash
# 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 (tier selection, 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 awareness** | Cost callbacks / monitoring — usage reported *after* the model returns | Per-turn caps **visible to the agent** in its system prompt (output tokens, steps, tool wall-clock). Agent plans within them and refuses upfront when a brief overshoots. Optional per-spec `cost_budget` adds a hard pre-call abort. |
| **Reproducibility** | Re-run and hope the model samples the same way | Structured JSONL trace per session — diff across runs to catch regressions; the trace is the single source of truth for post-mortems instead of stitching logs together |
| **Topology** | Emergent agent-to-agent conversations decided at runtime | DAG declared upfront; render the graph before running it |

---

## 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:

```bash
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:

```bash
pip install "git+ssh://git@github.com/<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`](USER_GUIDE.md)
- Architecture overview: `docs/MASTER_ARCHITECTURE.md` (upstream repo)
- Versioning policy: `docs/policy/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.
