zag-agent 0.2.1__py3-none-any.whl

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

zag/process.py

@@ -0,0 +1,176 @@
+"""Subprocess helpers for invoking the zag CLI."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncGenerator
+
+from .types import AgentOutput, Event, ZagError, parse_event
+
+
+def default_bin() -> str:
+    """Return the zag binary path (``ZAG_BIN`` env or ``"zag"``)."""
+    return os.environ.get("ZAG_BIN", "zag")
+
+
+async def exec_zag(bin: str, args: list[str]) -> AgentOutput:
+    """Run ``zag`` and return parsed :class:`AgentOutput`.
+
+    Raises :class:`ZagError` on non-zero exit.
+    """
+    proc = await asyncio.create_subprocess_exec(
+        bin,
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout_bytes, stderr_bytes = await proc.communicate()
+    stdout = stdout_bytes.decode()
+    stderr = stderr_bytes.decode()
+
+    if proc.returncode != 0:
+        raise ZagError(
+            f"zag exited with code {proc.returncode}: {stderr or stdout}",
+            proc.returncode,
+            stderr,
+        )
+
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise ZagError(
+            f"Failed to parse zag JSON output: {stdout[:200]}",
+            proc.returncode,
+            stderr,
+        ) from exc
+
+    return AgentOutput.from_dict(data)
+
+
+async def stream_zag(bin: str, args: list[str]) -> AsyncGenerator[Event, None]:
+    """Run ``zag`` in streaming mode and yield :class:`Event` objects (NDJSON)."""
+    proc = await asyncio.create_subprocess_exec(
+        bin,
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    assert proc.stdout is not None
+    assert proc.stderr is not None
+
+    while True:
+        line = await proc.stdout.readline()
+        if not line:
+            break
+        text = line.decode().strip()
+        if not text:
+            continue
+        try:
+            data = json.loads(text)
+            yield parse_event(data)
+        except (json.JSONDecodeError, ValueError):
+            continue
+
+    stderr_bytes = await proc.stderr.read()
+    await proc.wait()
+
+    if proc.returncode != 0:
+        stderr = stderr_bytes.decode()
+        raise ZagError(
+            f"zag exited with code {proc.returncode}",
+            proc.returncode,
+            stderr,
+        )
+
+
+class StreamingSession:
+    """A live streaming session with piped stdin and stdout.
+
+    Send NDJSON messages via :meth:`send`, read events via :meth:`events`,
+    then call :meth:`wait` when done.
+    """
+
+    def __init__(self, proc: asyncio.subprocess.Process) -> None:
+        self._proc = proc
+
+    @classmethod
+    async def create(cls, bin: str, args: list[str]) -> "StreamingSession":
+        proc = await asyncio.create_subprocess_exec(
+            bin,
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        return cls(proc)
+
+    async def send(self, message: str) -> None:
+        """Send a raw NDJSON line to the agent's stdin."""
+        assert self._proc.stdin is not None
+        self._proc.stdin.write((message + "\n").encode())
+        await self._proc.stdin.drain()
+
+    async def send_user_message(self, content: str) -> None:
+        """Send a user message to the agent."""
+        msg = json.dumps({"type": "user_message", "content": content})
+        await self.send(msg)
+
+    def close_input(self) -> None:
+        """Close stdin to signal no more input."""
+        if self._proc.stdin is not None:
+            self._proc.stdin.close()
+
+    async def events(self) -> AsyncGenerator[Event, None]:
+        """Async iterator over parsed Event objects from stdout."""
+        assert self._proc.stdout is not None
+        while True:
+            line = await self._proc.stdout.readline()
+            if not line:
+                break
+            text = line.decode().strip()
+            if not text:
+                continue
+            try:
+                data = json.loads(text)
+                yield parse_event(data)
+            except (json.JSONDecodeError, ValueError):
+                continue
+
+    async def wait(self) -> None:
+        """Wait for the process to exit. Raises ZagError on non-zero exit."""
+        self.close_input()
+        assert self._proc.stderr is not None
+        stderr_bytes = await self._proc.stderr.read()
+        await self._proc.wait()
+        if self._proc.returncode != 0:
+            stderr = stderr_bytes.decode()
+            raise ZagError(
+                f"zag exited with code {self._proc.returncode}",
+                self._proc.returncode,
+                stderr,
+            )
+
+
+def stream_with_input(bin: str, args: list[str]) -> StreamingSession:
+    """Create a StreamingSession (alias for StreamingSession.create)."""
+    # This is a sync wrapper that returns the coroutine; callers should await it
+    raise NotImplementedError("Use StreamingSession.create() directly")
+
+
+async def run_zag(bin: str, args: list[str]) -> None:
+    """Run ``zag`` interactively with inherited stdio.
+
+    Raises :class:`ZagError` on non-zero exit.
+    """
+    proc = await asyncio.create_subprocess_exec(bin, *args)
+    await proc.wait()
+
+    if proc.returncode != 0:
+        raise ZagError(
+            f"zag exited with code {proc.returncode}",
+            proc.returncode,
+            "",
+        )

zag/types.py

@@ -0,0 +1,302 @@
+"""Type definitions for zag agent output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ZagError(Exception):
+    """Error raised when the zag process fails."""
+
+    def __init__(self, message: str, exit_code: int | None, stderr: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+
+# ---------------------------------------------------------------------------
+# Usage
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Usage:
+    """Token usage statistics for an agent session."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int | None = None
+    cache_creation_tokens: int | None = None
+    web_search_requests: int | None = None
+    web_fetch_requests: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Usage:
+        return cls(
+            input_tokens=data.get("input_tokens", 0),
+            output_tokens=data.get("output_tokens", 0),
+            cache_read_tokens=data.get("cache_read_tokens"),
+            cache_creation_tokens=data.get("cache_creation_tokens"),
+            web_search_requests=data.get("web_search_requests"),
+            web_fetch_requests=data.get("web_fetch_requests"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Tool Result
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ToolResult:
+    """Result from a tool execution."""
+
+    success: bool
+    output: str | None = None
+    error: str | None = None
+    data: Any = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolResult:
+        return cls(
+            success=data.get("success", False),
+            output=data.get("output"),
+            error=data.get("error"),
+            data=data.get("data"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Content Blocks
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TextBlock:
+    """Plain text content block."""
+
+    type: str = "text"
+    text: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TextBlock:
+        return cls(text=data.get("text", ""))
+
+
+@dataclass
+class ToolUseBlock:
+    """Tool invocation content block."""
+
+    type: str = "tool_use"
+    id: str = ""
+    name: str = ""
+    input: Any = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolUseBlock:
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            input=data.get("input"),
+        )
+
+
+ContentBlock = TextBlock | ToolUseBlock
+
+
+def _parse_content_block(data: dict[str, Any]) -> ContentBlock:
+    if data.get("type") == "tool_use":
+        return ToolUseBlock.from_dict(data)
+    return TextBlock.from_dict(data)
+
+
+# ---------------------------------------------------------------------------
+# Events (tagged union on "type")
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InitEvent:
+    """Session initialization event."""
+
+    type: str = "init"
+    model: str = ""
+    tools: list[str] = field(default_factory=list)
+    working_directory: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> InitEvent:
+        return cls(
+            model=data.get("model", ""),
+            tools=data.get("tools", []),
+            working_directory=data.get("working_directory"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+@dataclass
+class UserMessageEvent:
+    """User message (replayed via --replay-user-messages)."""
+
+    type: str = "user_message"
+    content: list[ContentBlock] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> UserMessageEvent:
+        content = [_parse_content_block(b) for b in data.get("content", [])]
+        return cls(content=content)
+
+
+@dataclass
+class AssistantMessageEvent:
+    """Message from the assistant."""
+
+    type: str = "assistant_message"
+    content: list[ContentBlock] = field(default_factory=list)
+    usage: Usage | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AssistantMessageEvent:
+        content = [_parse_content_block(b) for b in data.get("content", [])]
+        usage_data = data.get("usage")
+        usage = Usage.from_dict(usage_data) if usage_data else None
+        return cls(content=content, usage=usage)
+
+
+@dataclass
+class ToolExecutionEvent:
+    """Tool execution event."""
+
+    type: str = "tool_execution"
+    tool_name: str = ""
+    tool_id: str = ""
+    input: Any = None
+    result: ToolResult = field(default_factory=lambda: ToolResult(success=False))
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolExecutionEvent:
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            tool_id=data.get("tool_id", ""),
+            input=data.get("input"),
+            result=ToolResult.from_dict(data.get("result", {})),
+        )
+
+
+@dataclass
+class ResultEvent:
+    """Final session result event."""
+
+    type: str = "result"
+    success: bool = False
+    message: str | None = None
+    duration_ms: int | None = None
+    num_turns: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ResultEvent:
+        return cls(
+            success=data.get("success", False),
+            message=data.get("message"),
+            duration_ms=data.get("duration_ms"),
+            num_turns=data.get("num_turns"),
+        )
+
+
+@dataclass
+class ErrorEvent:
+    """Error event."""
+
+    type: str = "error"
+    message: str = ""
+    details: Any = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ErrorEvent:
+        return cls(
+            message=data.get("message", ""),
+            details=data.get("details"),
+        )
+
+
+@dataclass
+class PermissionRequestEvent:
+    """Permission request event."""
+
+    type: str = "permission_request"
+    tool_name: str = ""
+    description: str = ""
+    granted: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PermissionRequestEvent:
+        return cls(
+            tool_name=data.get("tool_name", ""),
+            description=data.get("description", ""),
+            granted=data.get("granted", False),
+        )
+
+
+Event = (
+    InitEvent
+    | UserMessageEvent
+    | AssistantMessageEvent
+    | ToolExecutionEvent
+    | ResultEvent
+    | ErrorEvent
+    | PermissionRequestEvent
+)
+
+_EVENT_PARSERS: dict[str, type] = {
+    "init": InitEvent,
+    "user_message": UserMessageEvent,
+    "assistant_message": AssistantMessageEvent,
+    "tool_execution": ToolExecutionEvent,
+    "result": ResultEvent,
+    "error": ErrorEvent,
+    "permission_request": PermissionRequestEvent,
+}
+
+
+def parse_event(data: dict[str, Any]) -> Event:
+    """Parse a raw dict into the appropriate Event subtype."""
+    event_type = data.get("type", "")
+    parser = _EVENT_PARSERS.get(event_type)
+    if parser is None:
+        raise ValueError(f"Unknown event type: {event_type}")
+    return parser.from_dict(data)  # type: ignore[union-attr]
+
+
+# ---------------------------------------------------------------------------
+# AgentOutput
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AgentOutput:
+    """Unified output from an agent session."""
+
+    agent: str = ""
+    session_id: str = ""
+    events: list[Event] = field(default_factory=list)
+    result: str | None = None
+    is_error: bool = False
+    total_cost_usd: float | None = None
+    usage: Usage | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentOutput:
+        events = [parse_event(e) for e in data.get("events", [])]
+        usage_data = data.get("usage")
+        usage = Usage.from_dict(usage_data) if usage_data else None
+        return cls(
+            agent=data.get("agent", ""),
+            session_id=data.get("session_id", ""),
+            events=events,
+            result=data.get("result"),
+            is_error=data.get("is_error", False),
+            total_cost_usd=data.get("total_cost_usd"),
+            usage=usage,
+        )

zag_agent-0.2.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+zag/__init__.py,sha256=FWgja1DP4aO2vLdJHB7V12rUr4v1diHMCJC7sd3IJpc,676
+zag/builder.py,sha256=TQGYJlt8OX9WBFK-dFc8Mo8n_rdW6jpd9lYcTAeuPmc,10728
+zag/process.py,sha256=mc_zsJGscEgjTVIRi_9_xDhg6yIIRbG3VvPpopExL-A,5389
+zag/types.py,sha256=5OJYQpJJuyotp_HQP1L2BGaiBW-5rokMrQig6kZYKgA,8365
+zag_agent-0.2.1.dist-info/METADATA,sha256=_oM1P44MeuNO-lCZBqg8jHPNORfEs-0ivwW7IFPt6Ps,4182
+zag_agent-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+zag_agent-0.2.1.dist-info/top_level.txt,sha256=yf3HgUUit2iipiJk8Hw-xOXYQ0TV0Pm3ycYXzNWAHK8,4
+zag_agent-0.2.1.dist-info/RECORD,,

zag_agent-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zag_agent-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+zag