Metadata-Version: 2.4
Name: ziro
Version: 0.3.0
Summary: Deep LangGraph agent with memory, RAG, skills, OpenRouter, and Langfuse
Project-URL: Repository, https://github.com/hRupanjan/ziro
Project-URL: Issues, https://github.com/hRupanjan/ziro/issues
Author-email: hRupanjan <hrupanjan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,langgraph,llm,memory,rag,tui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11.9
Requires-Dist: httpx~=0.28.1
Requires-Dist: loguru~=0.7.3
Requires-Dist: python-dotenv~=1.2.2
Requires-Dist: rich~=15.0.0
Requires-Dist: textual~=8.2.7
Requires-Dist: ziro-core
Provides-Extra: all
Requires-Dist: ziro-core[all]; extra == 'all'
Provides-Extra: guardrails-local
Requires-Dist: ziro-core[guardrails-local]; extra == 'guardrails-local'
Provides-Extra: voice-local
Requires-Dist: ziro-core[voice-local]; extra == 'voice-local'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://ziro-agent.com/ziro-logo-full-dark.png">
    <img src="https://ziro-agent.com/ziro-logo-full-light.png" alt="Ziro" width="300">
  </picture>
</p>

<p align="center">
  <a href="https://pypi.org/project/ziro/"><img src="https://img.shields.io/pypi/v/ziro" alt="PyPI"></a>
  <a href="https://github.com/hRupanjan/ziro/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/ziro" alt="License"></a>
  <a href="https://pypi.org/project/ziro/"><img src="https://img.shields.io/pypi/pyversions/ziro" alt="Python versions"></a>
</p>

A terminal coding and research agent with persistent memory, RAG, progressive tool
loading, subagents, MCP support, a skills library, configurable guardrails, and
automatic context compaction. Runs on **OpenRouter, Anthropic, OpenAI, or any
OpenAI/Anthropic-compatible endpoint** you point it at.

Two runtime modes, no config switch: SQLite + FAISS for local dev, PostgreSQL +
pgvector when `DATABASE_URL` is set.

## Install

The install script needs only Python 3.11.9+ and creates an isolated
environment. No pipx, no uv, no admin rights.

```bash
# macOS / Linux
curl -fsSL https://ziro-agent.com/install.sh | bash
```

```powershell
# Windows
iwr -useb https://ziro-agent.com/install.ps1 | iex
```

Both take `--version <v>`, `--uninstall`, and `--help`. Already have a Python
environment you like? `pip install ziro` works too.

## First run

```bash
ziro
```

With no arguments, `ziro` walks you through setup in the TUI: an API-key wizard
(get one at [openrouter.ai/keys](https://openrouter.ai/keys)), then optional
model / theme / advanced sections, then user, thread, and agent pickers, then
straight into chat. Re-run it any time with `ziro setup`.

```bash
ziro --user alice                          # skip the user picker
ziro --user alice --agent researcher       # pick an agent up front
ziro --user alice --flavour engineering    # scope to a workspace flavour
ziro --user alice --thread alice_abc12345  # resume a past conversation
ziro --user alice -p "summarize ./notes"   # headless: one turn, print, exit
ziro --user alice -p "..." --json          # headless, machine-readable
```

User ids are 1-64 characters of `[A-Za-z0-9_-]`.

## Features

**Agents and workspaces**

- **Multi-agent**: run as one of several named agents, each with its own persona,
  model, provider, tools, MCP servers, guardrails, permissions, and compaction
  policy. Per-agent on/off flags.
- **Flavours**: a workspace container chosen once at launch (`chat`, `engineering`,
  `research`, `safe`) that scopes which agents and threads you see, shares one
  memory across the team, and layers a policy overlay plus a dominant persona on
  top of its members.
- **Subagents**: delegate a self-contained subtask to a child agent in isolated
  context. Each is a single-file `*.agent.md` definition (persona plus scoped
  tools and skills) whose permissions are intersected with the parent's, never
  widened. Eight ship built in, including `scout`, `solver`, `reviewer`, `tester`,
  and `fact_checker`. Children can run in the background and report back
  unprompted when they finish.
- **Execution modes**: switch an agent live between `normal`, `plan` (read-only,
  with an explicit approval gate before anything runs), `ask` (confirm each write
  or command), and `auto`. Modes overlay the permission layer, so they compose
  with whatever policy the agent already has.

**Memory and context**

- **Long-term memory** for user-scoped and agent-scoped facts, persisted across
  sessions, plus per-project memory keyed to the workspace.
- **Thread resumption**: pick up any prior conversation by id, with AI-generated
  thread titles.
- **Context compaction**: older turns fold into a running summary as a request
  nears the model's window; recent turns stay verbatim. YAML-driven and
  model-aware, so the budget math tracks the actual context length.
- **RAG**: semantic search over indexed documents (`.txt`, `.pdf`, `.md`,
  directories).
- **Skills library**: index `SKILL.md` files; the agent retrieves relevant skills
  and loads their reference files on demand.

**Tools**

- **Progressive tool loading**: tools are deferred by default. The LLM discovers
  and activates only what it needs via `search_tools` / `load_tools`, so a large
  registry costs no context until it is used.
- **Filesystem**: `read_file`, `grep`, and `glob_files` as always-on core tools,
  plus ask-gated `write_file` / `edit_file`. Pure stdlib, identical on Windows and
  POSIX, confined to the project root.
- **Shell**: an optional `run_shell` that runs real commands on the host or in a
  Docker sandbox, with a cross-platform bash mode so pipes, quoting, and heredocs
  behave the same everywhere. Background execution is supported, and durable
  background shells survive a restart.
- **Web**: SSRF-guarded `web_fetch(url)` and a `web_search` backed by DuckDuckGo
  (keyless) or your own SearXNG.
- **MCP**: connect external MCP servers over stdio, SSE, streamable HTTP, or
  WebSocket, with OAuth. Persistent sessions cut per-call latency and a failing
  server never takes the rest down.
- **Plugins**: install Claude Code plugins from a git URL, a local path, or a
  marketplace, and use their skills, agents, prompt-macro commands, MCP servers,
  and hooks. Third-party code is trust-gated: shell hooks and stdio-MCP
  subprocesses stay inert until you consent, and editing any file revokes trust.
  Reads the native `~/.claude/plugins` layout, so nothing needs re-authoring.

**Safety**

- **Tool permissions**: per-agent allow / deny / ask policy over tool and
  namespace globs. An `ask` triggers human-in-the-loop approval with
  allow-once, allow-thread, or allow-always memory. `shell:*` ships
  dangerous-default-deny.
- **Guardrails**: configurable input and output guards (regex injection, ML
  classifier, PII via Presidio, Llama Guard content safety), all YAML-driven.
- **Hooks**: declarative lifecycle interception across ten events, with Python or
  shell callables and glob matchers. Powers permission gating, shell audit, and
  loop detection.
- **Containment for autonomous agents**: agents that hold shell and write access
  do not hold web tools, cannot write to the control plane (secrets, policy
  files, `.git`), and run behind always-on egress and loop guards.

**Interface**

- **Interactive TUI**: transcript with live token streaming, a todo and
  active-tools side pane, a context-usage meter, an MCP control panel, approval
  and question modals, and four themes. Paints in about 1.6 seconds and is usable
  while the engine builds on a background thread; anything you type early is
  queued and runs in order.
- **Slash commands** dispatched before the LLM, so they cost no model call and do
  not pollute the transcript.
- **Human handoff and clarifying questions**: the agent can pause a turn for a
  human operator, or ask 1-4 structured multiple-choice questions and fold the
  answers back in.
- **Local voice**: optional push-to-talk speech I/O with faster-whisper STT and
  Piper TTS, fully on-device, no cloud key required.
- **Headless and queued**: single-turn `-p` output (text or JSON), plus a
  background worker pool that survives restart.
- **Observability**: Langfuse and LangSmith tracing, both optional.

## Environment variables

| Variable | Required | Purpose |
|---|---|---|
| `OPENROUTER_API_KEY` | Yes* | LLM access via OpenRouter (*only when the active provider is `openrouter`) |
| `OPENROUTER_MODEL` | No | Model override (default: `google/gemini-2.5-flash-lite`) |
| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | No | Key for the `anthropic` / `openai` provider (with `ANTHROPIC_MODEL` / `OPENAI_MODEL`) |
| `<LABEL>_API_KEY` | No | Key for a custom provider named `<label>` in `~/.ziro/custom_providers.json` |
| `ZIRO_LLM_PROVIDER` | No | Global default provider when an agent pins no `provider:` (default: `openrouter`) |
| `ZIRO_REASONING_EFFORT` | No | Extended reasoning: `low` / `medium` / `high` (empty disables) |
| `DATABASE_URL` | No | Enables the production PostgreSQL + pgvector backends |
| `ZIRO_STRICT_SECURITY` | No | Force-inert all dangerous plugin components, fail-closed |
| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | No | Langfuse observability |
| `LANGFUSE_HOST` | No | Langfuse host (default: `https://cloud.langfuse.com`) |
| `LANGCHAIN_TRACING_V2` / `LANGCHAIN_API_KEY` | No | LangSmith tracing |

Model tiers are also supported: set `<PROVIDER>_PLANNING_MODEL`,
`<PROVIDER>_EXECUTION_MODEL`, or `<PROVIDER>_FAST_EXECUTION_MODEL` and reference
them as `${EXECUTION_MODEL}` in any agent's `model:` field.

## Slash commands

Typed into a running session and dispatched before the LLM.

| Command | Purpose |
|---|---|
| `/help` (`/h`) | List commands grouped by category |
| `/user [id]` | List users, or switch user (fresh thread, separate memories) |
| `/agent [id]` | Switch agent (rebuilds the session, fresh thread) |
| `/thread [n\|id\|new]` (`/threads`, `/resume`) | List, resume, or start threads |
| `/new` (Ctrl+N) | Start a fresh thread |
| `/model [id]` | Switch the model, rebuilding the LLM |
| `/settings` | Edit API key, model, theme, Langfuse, and database |
| `/think <high\|medium\|low\|off>` | Set reasoning effort live |
| `/memory` | Show and manage project memory |
| `/scratch` | Show the per-thread scratchpad |
| `/tasks` | List the thread's running background shells and subagents |
| `/voice [on\|off]` | Toggle push-to-talk voice I/O |
| `/img <path> [text]` | Attach an image to this turn |
| `/mcp [server]` | Show MCP servers (TUI: control panel, Ctrl+O) |
| `/capability [list\|add\|remove]` | Manage optional capabilities and their models |
| `/skills` | Show reachable skills, tagged `bundled` / `workspace` / `plugin` |
| `/plugins` (`/plugin`) | Plugin panel; `install <src>` → `confirm [safe]`, `update`, `remove`, `info`, `enable`, `disable`, `marketplace …`, `reload` |
| `/stop` (`/halt`) | Abort the turn in flight (Ctrl+S) |
| `/save [path]` | Save the transcript to JSON |
| `/quit` (`/exit`, `/q`) | Exit the session |

## Managing agents and plugins

```bash
ziro plugin install https://github.com/owner/some-plugin.git   # or a local path
ziro plugin marketplace add acme https://github.com/acme/marketplace.git
ziro plugin install acme:some-plugin
ziro plugin list

python -m app.cli.manage_agents list
python -m app.cli.manage_agents add my-agent --name "My Agent"
python -m app.cli.manage_agents set-model my-agent anthropic/claude-sonnet-4-5
python -m app.cli.manage_agents add-subagent my-scout --namespaces rag --skills deep-research
```

Agents resolve their config **most-specific-first** across three roots:
`<project>/.ziro/agents/<id>/` → `~/.ziro/agents/<id>/` → the bundled package. So
you can override or add agents for an installed ziro without touching the
package: drop files under `~/.ziro/agents/<id>/`.

## Documentation

- Full docs: **[docs.ziro-agent.com](https://docs.ziro-agent.com)**
- Architecture, subsystem internals, and development setup:
  [CONTRIBUTING.md](https://github.com/hRupanjan/ziro/blob/master/CONTRIBUTING.md)
- Source and issues: [github.com/hRupanjan/ziro](https://github.com/hRupanjan/ziro)

## License

MIT. See [LICENSE](https://github.com/hRupanjan/ziro/blob/master/LICENSE).
