agntz 0.1.0__tar.gz

agntz-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.basedpyright/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

agntz-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: agntz
+Version: 0.1.0
+Summary: Python SDK and hosted client for Agntz
+Author: Agntz
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.31.0; extra == 'dev'
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.75.0; extra == 'litellm'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# Agntz Python
+
+Python SDK and hosted client for Agntz.
+
+The compatibility rule is simple: an agent definition YAML file should have the
+same observable behavior in the TypeScript and Python runtimes. Python code uses
+Python naming conventions, but the agent, run, session, trace, and tool concepts
+match the TypeScript SDK.
+
+## Install
+
+```bash
+pip install agntz
+```
+
+For local LLM execution through LiteLLM:
+
+```bash
+pip install "agntz[litellm]"
+```
+
+## Create an agent
+
+Save this as `agents/support.yaml`:
+
+```yaml
+id: support
+kind: llm
+name: Support Assistant
+description: Answers support questions with a concise plan.
+model:
+  provider: openai
+  name: gpt-5.4
+  temperature: 0.2
+instruction: |
+  You are a careful support agent.
+prompt: |
+  Help with this request: {{userQuery}}
+inputSchema:
+  userQuery: string
+outputSchema:
+  answer: string
+  confidence: number
+```
+
+The same file can be loaded by the TypeScript and Python SDKs.
+
+## Run locally
+
+```python
+from agntz import LiteLLMModelProvider, agntz
+
+client = agntz(
+    agents="./agents",
+    model_provider=LiteLLMModelProvider(),
+)
+
+result = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "Help me debug this invoice"},
+)
+
+print(result.output)
+print(result.session_id)
+```
+
+Use `client.agents.arun(...)` inside an existing event loop.
+
+## Hosted client
+
+```python
+import os
+from agntz import AgntzClient
+
+client = AgntzClient(
+    api_key=os.environ["AGNTZ_API_KEY"],
+    base_url="https://api.agntz.co",
+)
+
+result = client.agents.run(agent_id="support", input="Hello")
+```
+
+The async hosted client has the same resource shape:
+
+```python
+from agntz import AsyncAgntzClient
+
+async with AsyncAgntzClient(api_key="...", base_url="https://api.agntz.co") as client:
+    result = await client.agents.run(agent_id="support", input="Hello")
+```
+
+Pass runtime namespace grants with `context` when the run needs resource access:
+
+```python
+result = client.agents.run(
+    agent_id="support",
+    input="Hello",
+    context=["app/user/u_123"],
+)
+```
+
+## Local tools
+
+```python
+from typing import Any
+
+from pydantic import BaseModel
+from agntz import LiteLLMModelProvider, agntz, tool
+
+
+class LookupInput(BaseModel):
+    order_id: str
+
+
+def lookup_order(args: LookupInput) -> dict[str, Any]:
+    return {"status": "shipped", "eta": "Tomorrow"}
+
+
+client = agntz(
+    agents="./agents",
+    tools=[
+        tool(
+            name="lookup_order",
+            description="Look up an order by ID",
+            input_schema=LookupInput,
+            execute=lookup_order,
+        )
+    ],
+    model_provider=LiteLLMModelProvider(),
+)
+```
+
+Reference the tool from YAML:
+
+```yaml
+tools:
+  - kind: local
+    tools: [lookup_order]
+```
+
+LLM agents can also call HTTP tools, MCP tools over HTTP JSON-RPC, and
+agent-as-tool entries from the same manifest tool declarations used by the
+TypeScript runtime.
+
+## Sessions
+
+Pass the same `session_id` across runs to continue a conversation. Local
+sessions are persisted by the configured store and are replayed into model calls.
+
+```python
+first = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "Hi, I need help"},
+    session_id="customer-42",
+)
+
+second = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "My order is #12345"},
+    session_id=first.session_id,
+)
+
+messages = client.sessions.get_messages("customer-42")
+```
+
+## Runs and traces
+
+Local execution records runs, sessions, and trace spans. The same store backs all
+three surfaces.
+
+```python
+runs = client.runs.list(status="completed")
+trace_rows = client.traces.list(agent_id="support")
+
+trace_id = trace_rows["rows"][0]["traceId"]
+detail = client.traces.get(trace_id)
+
+print(detail["summary"])
+print(detail["spans"])
+```
+
+## SQLite persistence
+
+```python
+from agntz import LiteLLMModelProvider, SQLiteStore, agntz
+
+client = agntz(
+    agents="./agents",
+    store=SQLiteStore("./agntz.sqlite"),
+    model_provider=LiteLLMModelProvider(),
+)
+```
+
+SQLite persists local runs, trace spans, sessions, and messages across process
+restarts.
+
+## Memrez
+
+The Python package includes the same namespace-grant and memrez core primitives
+as the TypeScript package.
+
+```python
+from agntz.memrez import create_memrez
+
+memrez = create_memrez()
+memrez.write(["app/user/u_123"], "Prefers metric units.", topics_hint=["prefs"])
+entries = memrez.read(["app/user/u_123"], "prefs")
+```
+
+## CLI
+
+```bash
+agntz validate ./agents
+agntz run ./agents support --input '{"userQuery":"hello"}'
+```
+
+## Current parity
+
+Implemented in this package:
+
+- Hosted sync and async clients for run, run stream, runs, and traces.
+- Local YAML execution for `llm`, `tool`, `sequential`, and `parallel` agents.
+- Local Python tools, HTTP tools, MCP JSON-RPC tools, and agent-as-tool calls.
+- Runtime namespace grants and the in-memory memrez core.
+- LiteLLM-backed model execution with tool-call loop support.
+- Memory and SQLite stores for runs, trace spans, sessions, and messages.
+- Contract fixtures shared with the TypeScript manifest package.
+
+Still intentionally outside this first Python package slice:
+
+- The hosted app and worker remain TypeScript services.
+- Python does not reimplement the TypeScript eval product yet.
+- Streaming token deltas for local Python execution are not exposed yet.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,litellm]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+.venv/bin/python -m basedpyright
+.venv/bin/python -m build
+```

agntz-0.1.0/README.md

@@ -0,0 +1,244 @@
+# Agntz Python
+
+Python SDK and hosted client for Agntz.
+
+The compatibility rule is simple: an agent definition YAML file should have the
+same observable behavior in the TypeScript and Python runtimes. Python code uses
+Python naming conventions, but the agent, run, session, trace, and tool concepts
+match the TypeScript SDK.
+
+## Install
+
+```bash
+pip install agntz
+```
+
+For local LLM execution through LiteLLM:
+
+```bash
+pip install "agntz[litellm]"
+```
+
+## Create an agent
+
+Save this as `agents/support.yaml`:
+
+```yaml
+id: support
+kind: llm
+name: Support Assistant
+description: Answers support questions with a concise plan.
+model:
+  provider: openai
+  name: gpt-5.4
+  temperature: 0.2
+instruction: |
+  You are a careful support agent.
+prompt: |
+  Help with this request: {{userQuery}}
+inputSchema:
+  userQuery: string
+outputSchema:
+  answer: string
+  confidence: number
+```
+
+The same file can be loaded by the TypeScript and Python SDKs.
+
+## Run locally
+
+```python
+from agntz import LiteLLMModelProvider, agntz
+
+client = agntz(
+    agents="./agents",
+    model_provider=LiteLLMModelProvider(),
+)
+
+result = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "Help me debug this invoice"},
+)
+
+print(result.output)
+print(result.session_id)
+```
+
+Use `client.agents.arun(...)` inside an existing event loop.
+
+## Hosted client
+
+```python
+import os
+from agntz import AgntzClient
+
+client = AgntzClient(
+    api_key=os.environ["AGNTZ_API_KEY"],
+    base_url="https://api.agntz.co",
+)
+
+result = client.agents.run(agent_id="support", input="Hello")
+```
+
+The async hosted client has the same resource shape:
+
+```python
+from agntz import AsyncAgntzClient
+
+async with AsyncAgntzClient(api_key="...", base_url="https://api.agntz.co") as client:
+    result = await client.agents.run(agent_id="support", input="Hello")
+```
+
+Pass runtime namespace grants with `context` when the run needs resource access:
+
+```python
+result = client.agents.run(
+    agent_id="support",
+    input="Hello",
+    context=["app/user/u_123"],
+)
+```
+
+## Local tools
+
+```python
+from typing import Any
+
+from pydantic import BaseModel
+from agntz import LiteLLMModelProvider, agntz, tool
+
+
+class LookupInput(BaseModel):
+    order_id: str
+
+
+def lookup_order(args: LookupInput) -> dict[str, Any]:
+    return {"status": "shipped", "eta": "Tomorrow"}
+
+
+client = agntz(
+    agents="./agents",
+    tools=[
+        tool(
+            name="lookup_order",
+            description="Look up an order by ID",
+            input_schema=LookupInput,
+            execute=lookup_order,
+        )
+    ],
+    model_provider=LiteLLMModelProvider(),
+)
+```
+
+Reference the tool from YAML:
+
+```yaml
+tools:
+  - kind: local
+    tools: [lookup_order]
+```
+
+LLM agents can also call HTTP tools, MCP tools over HTTP JSON-RPC, and
+agent-as-tool entries from the same manifest tool declarations used by the
+TypeScript runtime.
+
+## Sessions
+
+Pass the same `session_id` across runs to continue a conversation. Local
+sessions are persisted by the configured store and are replayed into model calls.
+
+```python
+first = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "Hi, I need help"},
+    session_id="customer-42",
+)
+
+second = client.agents.run(
+    agent_id="support",
+    input={"userQuery": "My order is #12345"},
+    session_id=first.session_id,
+)
+
+messages = client.sessions.get_messages("customer-42")
+```
+
+## Runs and traces
+
+Local execution records runs, sessions, and trace spans. The same store backs all
+three surfaces.
+
+```python
+runs = client.runs.list(status="completed")
+trace_rows = client.traces.list(agent_id="support")
+
+trace_id = trace_rows["rows"][0]["traceId"]
+detail = client.traces.get(trace_id)
+
+print(detail["summary"])
+print(detail["spans"])
+```
+
+## SQLite persistence
+
+```python
+from agntz import LiteLLMModelProvider, SQLiteStore, agntz
+
+client = agntz(
+    agents="./agents",
+    store=SQLiteStore("./agntz.sqlite"),
+    model_provider=LiteLLMModelProvider(),
+)
+```
+
+SQLite persists local runs, trace spans, sessions, and messages across process
+restarts.
+
+## Memrez
+
+The Python package includes the same namespace-grant and memrez core primitives
+as the TypeScript package.
+
+```python
+from agntz.memrez import create_memrez
+
+memrez = create_memrez()
+memrez.write(["app/user/u_123"], "Prefers metric units.", topics_hint=["prefs"])
+entries = memrez.read(["app/user/u_123"], "prefs")
+```
+
+## CLI
+
+```bash
+agntz validate ./agents
+agntz run ./agents support --input '{"userQuery":"hello"}'
+```
+
+## Current parity
+
+Implemented in this package:
+
+- Hosted sync and async clients for run, run stream, runs, and traces.
+- Local YAML execution for `llm`, `tool`, `sequential`, and `parallel` agents.
+- Local Python tools, HTTP tools, MCP JSON-RPC tools, and agent-as-tool calls.
+- Runtime namespace grants and the in-memory memrez core.
+- LiteLLM-backed model execution with tool-call loop support.
+- Memory and SQLite stores for runs, trace spans, sessions, and messages.
+- Contract fixtures shared with the TypeScript manifest package.
+
+Still intentionally outside this first Python package slice:
+
+- The hosted app and worker remain TypeScript services.
+- Python does not reimplement the TypeScript eval product yet.
+- Streaming token deltas for local Python execution are not exposed yet.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,litellm]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+.venv/bin/python -m basedpyright
+.venv/bin/python -m build
+```

agntz-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "agntz"
+version = "0.1.0"
+description = "Python SDK and hosted client for Agntz"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Agntz" }]
+dependencies = [
+  "httpx>=0.28.0",
+  "pydantic>=2.8.0",
+  "PyYAML>=6.0.0",
+]
+
+[project.optional-dependencies]
+litellm = [
+  "litellm>=1.75.0",
+]
+postgres = [
+  "psycopg[binary]>=3.2.0",
+]
+dev = [
+  "build>=1.2.0",
+  "basedpyright>=1.31.0",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.8.0",
+]
+
+[project.scripts]
+agntz = "agntz.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agntz"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.basedpyright]
+include = ["src", "tests"]
+typeCheckingMode = "standard"
+pythonVersion = "3.11"
+reportUnknownMemberType = "none"
+reportUnknownVariableType = "none"
+reportUnknownArgumentType = "none"

agntz-0.1.0/src/agntz/__init__.py

@@ -0,0 +1,96 @@
+"""Python SDK and hosted client for Agntz."""
+
+from .client import (
+    AgntzClient,
+    AgntzError,
+    AsyncAgntzClient,
+    AuthenticationError,
+    NotFoundError,
+    StreamError,
+)
+from .context import (
+    NamespaceGrantError,
+    NamespaceGrantPolicy,
+    ProtectedNamespaceRule,
+    normalize_namespace_grant,
+    normalize_namespace_grants,
+    validate_namespace_grant_policy,
+)
+from .core import (
+    GenerateTextResult,
+    LiteLLMModelProvider,
+    ModelMessage,
+    ModelProvider,
+    ModelTool,
+    ResourceProvider,
+    ResourceProviderToolDefinition,
+    ResourceRegistrationContext,
+    ResourceToolContext,
+    ToolCall,
+    ToolDefinition,
+    ToolResult,
+    tool,
+)
+from .memrez import Memrez, MemrezScopeError, create_memrez
+from .memrez_postgres import PostgresMemoryStore, PostgresMemoryStoreOptions
+from .memrez_provider import MemoryResourceProvider, create_memory_resource_provider
+from .memrez_reasoner import AgntzReasoner, agntz_reasoner, memrez_agents_path
+from .memrez_sqlite import SqliteMemoryStore, SqliteMemoryStoreOptions
+from .sdk import LocalClient, agntz
+from .stores import (
+    LocalMessageRecord,
+    LocalSessionSummary,
+    LocalTraceSpanRecord,
+    MemoryStore,
+    SQLiteStore,
+)
+
+__all__ = [
+    "__version__",
+    "AgntzClient",
+    "AgntzError",
+    "AgntzReasoner",
+    "AsyncAgntzClient",
+    "AuthenticationError",
+    "GenerateTextResult",
+    "LiteLLMModelProvider",
+    "LocalClient",
+    "LocalMessageRecord",
+    "LocalSessionSummary",
+    "LocalTraceSpanRecord",
+    "ModelMessage",
+    "ModelProvider",
+    "ModelTool",
+    "MemoryStore",
+    "MemoryResourceProvider",
+    "Memrez",
+    "MemrezScopeError",
+    "NamespaceGrantError",
+    "NamespaceGrantPolicy",
+    "NotFoundError",
+    "PostgresMemoryStore",
+    "PostgresMemoryStoreOptions",
+    "ProtectedNamespaceRule",
+    "ResourceProvider",
+    "ResourceProviderToolDefinition",
+    "ResourceRegistrationContext",
+    "ResourceToolContext",
+    "SQLiteStore",
+    "SqliteMemoryStore",
+    "SqliteMemoryStoreOptions",
+    "StreamError",
+    "ToolCall",
+    "ToolDefinition",
+    "ToolResult",
+    "agntz",
+    "agntz_reasoner",
+    "create_memory_resource_provider",
+    "create_memrez",
+    "memrez_agents_path",
+    "normalize_namespace_grant",
+    "normalize_namespace_grants",
+    "validate_namespace_grant_policy",
+    "tool",
+]
+
+__version__ = "0.1.0"