zag-agent 0.2.1__tar.gz

zag_agent-0.2.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: zag-agent
+Version: 0.2.1
+Summary: Python SDK for zag — a unified CLI for AI coding agents
+Author: Niclas Lindstedt
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/niclaslindstedt/zag
+Project-URL: Repository, https://github.com/niclaslindstedt/zag
+Keywords: zag,ai,agent,claude,codex,gemini,copilot,ollama
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Zag Python Binding
+
+Python binding for [zag](https://github.com/niclaslindstedt/zag) — a unified CLI for AI coding agents.
+
+## Prerequisites
+
+- Python 3.10+
+- The `zag` CLI binary installed and on your `PATH` (or set via `ZAG_BIN` env var)
+
+## Installation
+
+```bash
+pip install zag-agent
+```
+
+For development from source:
+
+```bash
+cd bindings/python
+pip install -e .
+```
+
+## Quick start
+
+```python
+from zag import ZagBuilder
+
+output = await ZagBuilder() \
+    .provider("claude") \
+    .model("sonnet") \
+    .auto_approve() \
+    .exec("write a hello world program")
+
+print(output.result)
+```
+
+## Streaming
+
+```python
+from zag import ZagBuilder
+
+async for event in await ZagBuilder().provider("claude").stream("analyze code"):
+    print(event.type, event)
+```
+
+## Builder methods
+
+| Method | Description |
+|--------|-------------|
+| `.provider(name)` | Set provider: `"claude"`, `"codex"`, `"gemini"`, `"copilot"`, `"ollama"` |
+| `.model(name)` | Set model name or size alias (`"small"`, `"medium"`, `"large"`) |
+| `.system_prompt(text)` | Set a system prompt |
+| `.root(path)` | Set the working directory |
+| `.auto_approve()` | Skip permission prompts |
+| `.add_dir(path)` | Add an additional directory (chainable) |
+| `.json_mode()` | Request JSON output |
+| `.json_schema(schema)` | Validate output against a JSON schema (implies `.json_mode()`) |
+| `.json_stream()` | Enable streaming NDJSON output |
+| `.worktree(name=None)` | Run in an isolated git worktree |
+| `.sandbox(name=None)` | Run in a Docker sandbox |
+| `.session_id(uuid)` | Use a specific session ID |
+| `.output_format(fmt)` | Set output format (`"text"`, `"json"`, `"json-pretty"`, `"stream-json"`) |
+| `.input_format(fmt)` | Set input format (`"text"`, `"stream-json"` — Claude only) |
+| `.replay_user_messages()` | Re-emit user messages on stdout (Claude only) |
+| `.include_partial_messages()` | Include partial message chunks (Claude only) |
+| `.max_turns(n)` | Set the maximum number of agentic turns |
+| `.show_usage()` | Show token usage statistics (JSON output mode) |
+| `.size(size)` | Set Ollama model parameter size (e.g., `"2b"`, `"9b"`, `"35b"`) |
+| `.verbose()` | Enable verbose output |
+| `.quiet()` | Suppress non-essential output |
+| `.debug()` | Enable debug logging |
+| `.bin(path)` | Override the `zag` binary path |
+
+## Terminal methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.exec(prompt)` | `AgentOutput` | Run non-interactively, return structured output |
+| `.stream(prompt)` | `AsyncGenerator[Event]` | Stream NDJSON events |
+| `.exec_streaming(prompt)` | `StreamingSession` | Bidirectional streaming (Claude only) |
+| `.run(prompt=None)` | `None` | Start an interactive session (inherits stdio) |
+| `.resume(session_id)` | `None` | Resume a previous session by ID |
+| `.continue_last()` | `None` | Resume the most recent session |
+
+## How it works
+
+The SDK spawns the `zag` CLI as a subprocess (`zag exec -o json` or `-o stream-json`) and parses the JSON/NDJSON output into typed dataclasses. Zero external dependencies — only the Python standard library.
+
+## Testing
+
+```bash
+pip install pytest pytest-asyncio
+pytest
+```
+
+## See also
+
+- [TypeScript SDK](../typescript/README.md)
+- [C# SDK](../csharp/README.md)
+- [Rust API (zag-agent)](../../zag-agent/README.md)
+- [All bindings](../README.md)
+
+## License
+
+[MIT](../../LICENSE)

zag_agent-0.2.1/README.md

@@ -0,0 +1,105 @@
+# Zag Python Binding
+
+Python binding for [zag](https://github.com/niclaslindstedt/zag) — a unified CLI for AI coding agents.
+
+## Prerequisites
+
+- Python 3.10+
+- The `zag` CLI binary installed and on your `PATH` (or set via `ZAG_BIN` env var)
+
+## Installation
+
+```bash
+pip install zag-agent
+```
+
+For development from source:
+
+```bash
+cd bindings/python
+pip install -e .
+```
+
+## Quick start
+
+```python
+from zag import ZagBuilder
+
+output = await ZagBuilder() \
+    .provider("claude") \
+    .model("sonnet") \
+    .auto_approve() \
+    .exec("write a hello world program")
+
+print(output.result)
+```
+
+## Streaming
+
+```python
+from zag import ZagBuilder
+
+async for event in await ZagBuilder().provider("claude").stream("analyze code"):
+    print(event.type, event)
+```
+
+## Builder methods
+
+| Method | Description |
+|--------|-------------|
+| `.provider(name)` | Set provider: `"claude"`, `"codex"`, `"gemini"`, `"copilot"`, `"ollama"` |
+| `.model(name)` | Set model name or size alias (`"small"`, `"medium"`, `"large"`) |
+| `.system_prompt(text)` | Set a system prompt |
+| `.root(path)` | Set the working directory |
+| `.auto_approve()` | Skip permission prompts |
+| `.add_dir(path)` | Add an additional directory (chainable) |
+| `.json_mode()` | Request JSON output |
+| `.json_schema(schema)` | Validate output against a JSON schema (implies `.json_mode()`) |
+| `.json_stream()` | Enable streaming NDJSON output |
+| `.worktree(name=None)` | Run in an isolated git worktree |
+| `.sandbox(name=None)` | Run in a Docker sandbox |
+| `.session_id(uuid)` | Use a specific session ID |
+| `.output_format(fmt)` | Set output format (`"text"`, `"json"`, `"json-pretty"`, `"stream-json"`) |
+| `.input_format(fmt)` | Set input format (`"text"`, `"stream-json"` — Claude only) |
+| `.replay_user_messages()` | Re-emit user messages on stdout (Claude only) |
+| `.include_partial_messages()` | Include partial message chunks (Claude only) |
+| `.max_turns(n)` | Set the maximum number of agentic turns |
+| `.show_usage()` | Show token usage statistics (JSON output mode) |
+| `.size(size)` | Set Ollama model parameter size (e.g., `"2b"`, `"9b"`, `"35b"`) |
+| `.verbose()` | Enable verbose output |
+| `.quiet()` | Suppress non-essential output |
+| `.debug()` | Enable debug logging |
+| `.bin(path)` | Override the `zag` binary path |
+
+## Terminal methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.exec(prompt)` | `AgentOutput` | Run non-interactively, return structured output |
+| `.stream(prompt)` | `AsyncGenerator[Event]` | Stream NDJSON events |
+| `.exec_streaming(prompt)` | `StreamingSession` | Bidirectional streaming (Claude only) |
+| `.run(prompt=None)` | `None` | Start an interactive session (inherits stdio) |
+| `.resume(session_id)` | `None` | Resume a previous session by ID |
+| `.continue_last()` | `None` | Resume the most recent session |
+
+## How it works
+
+The SDK spawns the `zag` CLI as a subprocess (`zag exec -o json` or `-o stream-json`) and parses the JSON/NDJSON output into typed dataclasses. Zero external dependencies — only the Python standard library.
+
+## Testing
+
+```bash
+pip install pytest pytest-asyncio
+pytest
+```
+
+## See also
+
+- [TypeScript SDK](../typescript/README.md)
+- [C# SDK](../csharp/README.md)
+- [Rust API (zag-agent)](../../zag-agent/README.md)
+- [All bindings](../README.md)
+
+## License
+
+[MIT](../../LICENSE)

zag_agent-0.2.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zag-agent"
+version = "0.2.1"
+description = "Python SDK for zag — a unified CLI for AI coding agents"
+license = "MIT"
+requires-python = ">=3.10"
+readme = "README.md"
+keywords = ["zag", "ai", "agent", "claude", "codex", "gemini", "copilot", "ollama"]
+authors = [
+    { name = "Niclas Lindstedt" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/niclaslindstedt/zag"
+Repository = "https://github.com/niclaslindstedt/zag"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

zag_agent-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zag_agent-0.2.1/src/zag/__init__.py

@@ -0,0 +1,37 @@
+"""Python SDK for zag — a unified CLI for AI coding agents."""
+
+from .builder import ZagBuilder
+from .types import (
+    AgentOutput,
+    AssistantMessageEvent,
+    ContentBlock,
+    ErrorEvent,
+    Event,
+    InitEvent,
+    PermissionRequestEvent,
+    ResultEvent,
+    TextBlock,
+    ToolExecutionEvent,
+    ToolResult,
+    ToolUseBlock,
+    Usage,
+    ZagError,
+)
+
+__all__ = [
+    "ZagBuilder",
+    "AgentOutput",
+    "Usage",
+    "Event",
+    "InitEvent",
+    "AssistantMessageEvent",
+    "ToolExecutionEvent",
+    "ResultEvent",
+    "ErrorEvent",
+    "PermissionRequestEvent",
+    "ContentBlock",
+    "TextBlock",
+    "ToolUseBlock",
+    "ToolResult",
+    "ZagError",
+]

zag_agent-0.2.1/src/zag/builder.py

@@ -0,0 +1,306 @@
+"""Fluent builder for configuring and running zag agent sessions.
+
+Example::
+
+    from zag import ZagBuilder
+
+    output = await ZagBuilder() \\
+        .provider("claude") \\
+        .model("sonnet") \\
+        .auto_approve() \\
+        .exec("write a hello world program")
+
+    print(output.result)
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator
+
+from .process import default_bin, exec_zag, run_zag, stream_zag, stream_with_input
+from .types import AgentOutput, Event
+
+
+class ZagBuilder:
+    """Fluent builder for configuring and running zag agent sessions."""
+
+    def __init__(self) -> None:
+        self._bin: str = default_bin()
+        self._provider: str | None = None
+        self._model: str | None = None
+        self._system_prompt: str | None = None
+        self._root: str | None = None
+        self._auto_approve: bool = False
+        self._add_dirs: list[str] = []
+        self._json: bool = False
+        self._json_schema: dict | None = None
+        self._json_stream: bool = False
+        self._worktree: str | bool | None = None
+        self._sandbox: str | bool | None = None
+        self._verbose: bool = False
+        self._quiet: bool = False
+        self._debug: bool = False
+        self._session_id: str | None = None
+        self._output_format: str | None = None
+        self._input_format: str | None = None
+        self._replay_user_messages: bool = False
+        self._include_partial_messages: bool = False
+        self._max_turns: int | None = None
+        self._show_usage: bool = False
+        self._size: str | None = None
+
+    # -- Configuration methods -----------------------------------------------
+
+    def bin(self, path: str) -> ZagBuilder:
+        """Override the zag binary path (default: ``ZAG_BIN`` env or ``"zag"``)."""
+        self._bin = path
+        return self
+
+    def provider(self, p: str) -> ZagBuilder:
+        """Set the provider (e.g., ``"claude"``, ``"codex"``, ``"gemini"``)."""
+        self._provider = p
+        return self
+
+    def model(self, m: str) -> ZagBuilder:
+        """Set the model (e.g., ``"sonnet"``, ``"opus"``, ``"small"``)."""
+        self._model = m
+        return self
+
+    def system_prompt(self, p: str) -> ZagBuilder:
+        """Set a system prompt to configure agent behavior."""
+        self._system_prompt = p
+        return self
+
+    def root(self, r: str) -> ZagBuilder:
+        """Set the root directory for the agent to operate in."""
+        self._root = r
+        return self
+
+    def auto_approve(self, a: bool = True) -> ZagBuilder:
+        """Enable auto-approve mode (skip permission prompts)."""
+        self._auto_approve = a
+        return self
+
+    def add_dir(self, d: str) -> ZagBuilder:
+        """Add an additional directory for the agent to include."""
+        self._add_dirs.append(d)
+        return self
+
+    def json_mode(self) -> ZagBuilder:
+        """Request JSON output from the agent."""
+        self._json = True
+        return self
+
+    def json_schema(self, s: dict) -> ZagBuilder:
+        """Set a JSON schema for structured output validation. Implies ``json_mode()``."""
+        self._json_schema = s
+        self._json = True
+        return self
+
+    def json_stream(self) -> ZagBuilder:
+        """Enable streaming JSON output (NDJSON format)."""
+        self._json_stream = True
+        return self
+
+    def worktree(self, name: str | None = None) -> ZagBuilder:
+        """Enable worktree mode with an optional name."""
+        self._worktree = name if name is not None else True
+        return self
+
+    def sandbox(self, name: str | None = None) -> ZagBuilder:
+        """Enable sandbox mode with an optional name."""
+        self._sandbox = name if name is not None else True
+        return self
+
+    def verbose(self, v: bool = True) -> ZagBuilder:
+        """Enable verbose output."""
+        self._verbose = v
+        return self
+
+    def quiet(self, q: bool = True) -> ZagBuilder:
+        """Enable quiet mode."""
+        self._quiet = q
+        return self
+
+    def debug(self, d: bool = True) -> ZagBuilder:
+        """Enable debug logging."""
+        self._debug = d
+        return self
+
+    def session_id(self, id: str) -> ZagBuilder:
+        """Pre-set a session ID (UUID)."""
+        self._session_id = id
+        return self
+
+    def output_format(self, f: str) -> ZagBuilder:
+        """Set the output format (e.g., ``"text"``, ``"json"``, ``"stream-json"``)."""
+        self._output_format = f
+        return self
+
+    def input_format(self, f: str) -> ZagBuilder:
+        """Set the input format (Claude only)."""
+        self._input_format = f
+        return self
+
+    def replay_user_messages(self, r: bool = True) -> ZagBuilder:
+        """Re-emit user messages from stdin on stdout (Claude only)."""
+        self._replay_user_messages = r
+        return self
+
+    def include_partial_messages(self, i: bool = True) -> ZagBuilder:
+        """Include partial message chunks in streaming output (Claude only)."""
+        self._include_partial_messages = i
+        return self
+
+    def max_turns(self, n: int) -> ZagBuilder:
+        """Set the maximum number of agentic turns."""
+        self._max_turns = n
+        return self
+
+    def show_usage(self, s: bool = True) -> ZagBuilder:
+        """Show token usage statistics (only applies to JSON output mode)."""
+        self._show_usage = s
+        return self
+
+    def size(self, s: str) -> ZagBuilder:
+        """Set the Ollama model parameter size (e.g., ``"2b"``, ``"9b"``, ``"35b"``)."""
+        self._size = s
+        return self
+
+    # -- Arg building --------------------------------------------------------
+
+    def _global_args(self) -> list[str]:
+        args: list[str] = []
+        if self._provider:
+            args.extend(["-p", self._provider])
+        if self._model:
+            args.extend(["--model", self._model])
+        if self._system_prompt:
+            args.extend(["--system-prompt", self._system_prompt])
+        if self._root:
+            args.extend(["--root", self._root])
+        if self._auto_approve:
+            args.append("--auto-approve")
+        for d in self._add_dirs:
+            args.extend(["--add-dir", d])
+        if self._worktree is True:
+            args.append("-w")
+        elif isinstance(self._worktree, str):
+            args.extend(["-w", self._worktree])
+        if self._sandbox is True:
+            args.append("--sandbox")
+        elif isinstance(self._sandbox, str):
+            args.extend(["--sandbox", self._sandbox])
+        if self._verbose:
+            args.append("--verbose")
+        if self._quiet:
+            args.append("--quiet")
+        if self._debug:
+            args.append("--debug")
+        if self._session_id:
+            args.extend(["--session", self._session_id])
+        if self._max_turns is not None:
+            args.extend(["--max-turns", str(self._max_turns)])
+        if self._show_usage:
+            args.append("--show-usage")
+        if self._size:
+            args.extend(["--size", self._size])
+        return args
+
+    def _exec_args(self, prompt: str, *, streaming: bool = False) -> list[str]:
+        args = self._global_args()
+        args.append("exec")
+        if self._json:
+            args.append("--json")
+        if self._json_schema:
+            args.extend(["--json-schema", json.dumps(self._json_schema)])
+        if self._json_stream or streaming:
+            args.append("--json-stream")
+        if self._output_format:
+            args.extend(["-o", self._output_format])
+        if self._input_format:
+            args.extend(["-i", self._input_format])
+        if self._replay_user_messages:
+            args.append("--replay-user-messages")
+        if self._include_partial_messages:
+            args.append("--include-partial-messages")
+        # Default to json output for structured parsing
+        if not streaming and not self._output_format and not self._json_stream:
+            args.extend(["-o", "json"])
+        args.append(prompt)
+        return args
+
+    # -- Terminal methods ----------------------------------------------------
+
+    async def exec(self, prompt: str) -> AgentOutput:
+        """Run the agent non-interactively and return structured output.
+
+        Example::
+
+            output = await ZagBuilder().provider("claude").exec("say hello")
+            print(output.result)
+        """
+        args = self._exec_args(prompt)
+        return await exec_zag(self._bin, args)
+
+    async def exec_streaming(self, prompt: str) -> "StreamingSession":
+        """Run the agent with streaming input and output (Claude only).
+
+        Returns a StreamingSession for bidirectional communication.
+
+        Example::
+
+            session = await ZagBuilder().provider("claude").exec_streaming("hello")
+            await session.send_user_message("do something")
+            async for event in session.events():
+                print(event.type)
+            await session.wait()
+        """
+        from .process import StreamingSession as _StreamingSession
+
+        args = self._global_args()
+        args.append("exec")
+        args.extend(["-i", "stream-json"])
+        args.extend(["-o", "stream-json"])
+        args.append("--replay-user-messages")
+        if self._include_partial_messages:
+            args.append("--include-partial-messages")
+        args.append(prompt)
+        return await _StreamingSession.create(self._bin, args)
+
+    async def stream(self, prompt: str) -> AsyncGenerator[Event, None]:
+        """Run the agent in streaming mode, yielding events as they arrive.
+
+        Example::
+
+            async for event in await ZagBuilder().provider("claude").stream("analyze"):
+                print(event.type)
+        """
+        args = self._exec_args(prompt, streaming=True)
+        async for event in stream_zag(self._bin, args):
+            yield event
+
+    async def run(self, prompt: str | None = None) -> None:
+        """Start an interactive agent session (inherits stdio)."""
+        args = self._global_args()
+        args.append("run")
+        if self._json:
+            args.append("--json")
+        if self._json_schema:
+            args.extend(["--json-schema", json.dumps(self._json_schema)])
+        if prompt:
+            args.append(prompt)
+        await run_zag(self._bin, args)
+
+    async def resume(self, session_id: str) -> None:
+        """Resume a previous session by ID."""
+        args = self._global_args()
+        args.extend(["run", "--resume", session_id])
+        await run_zag(self._bin, args)
+
+    async def continue_last(self) -> None:
+        """Resume the most recent session."""
+        args = self._global_args()
+        args.extend(["run", "--continue"])
+        await run_zag(self._bin, args)