agntz 0.0.0__tar.gz

agntz-0.0.0/.gitignore

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

agntz-0.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# agntz
+
+## 0.0.0 - 2026-06-26
+
+- Establish the public baseline for the Python SDK.
+- Includes hosted sync/async clients, local manifest execution, resources, memrez integration, namespace grants, eval helpers, in-memory/SQLite/Postgres stores, and typed package exports.
+- Earlier PyPI releases were experimental pre-baseline iterations and should be yanked on the registry.

agntz-0.0.0/PKG-INFO

@@ -0,0 +1,421 @@
+Metadata-Version: 2.4
+Name: agntz
+Version: 0.0.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]"
+```
+
+For local LLM execution with Postgres-backed stores:
+
+```bash
+pip install "agntz[postgres,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, messages, agent versions,
+aliases, datasets, evals, eval runs, latest scores, and API keys across process
+restarts.
+
+## Versioned agents
+
+Agents loaded from YAML files are imported into the configured store as
+immutable versions. Unchanged files are deduped by content hash, so restarting a
+local process does not create duplicate versions.
+
+```python
+result = client.agents.run(
+    agent_id="support@latest",
+    input={"userQuery": "Help me debug this invoice"},
+)
+
+versions = client.agents.list_versions("support")
+client.agents.set_alias("support", "stable", versions[0].created_at)
+
+stable = client.agents.run(agent_id="support@stable", input={"userQuery": "Hello"})
+exact = client.agents.run(
+    agent_id=f"support@{versions[0].created_at}",
+    input={"userQuery": "Replay this exact version"},
+)
+```
+
+The same resource exposes `list`, `get`, `create`, `update`, `delete`,
+`get_version`, `activate_version`, `set_alias`, and `remove_alias` for local and
+hosted clients.
+
+## Datasets and evals
+
+Datasets are scoped to an agent, and eval definitions can point to a default
+dataset. Eval runs preserve immutable history and update the latest score for
+the eval, dataset, and resolved agent version.
+
+```python
+dataset = client.datasets.create(
+    agent_id="support",
+    name="Refund checks",
+    items=[
+        {
+            "id": "refund-1",
+            "input": {"userQuery": "How do I request a refund?"},
+            "expected": {"intent": "refund"},
+        }
+    ],
+)
+
+definition = client.evals.create(
+    agent_id="support",
+    name="Support quality",
+    default_dataset_id=dataset.id,
+    criteria=[{"id": "helpful", "name": "Helpful", "threshold": 0.7}],
+    pass_threshold=0.7,
+)
+
+run = client.evals.run(eval_id=definition.id, agent_version="latest")
+latest = client.evals.get_latest_score(
+    eval_id=definition.id,
+    dataset_id=dataset.id,
+    resolved_agent_version=run.agent_version,
+)
+```
+
+Hosted eval runs return immediately with `running` status. Poll
+`client.evals.get_run(run.id)` or use `client.evals.cancel_run(run.id)` to stop a
+run. Pending cases are marked `cancelled`; in-flight provider calls are
+best-effort and may finish before the background runner observes cancellation.
+
+## Hosted deployments
+
+Python no longer ships a hosted worker implementation. Use `AgntzClient` or
+`AsyncAgntzClient` to call the TypeScript worker hosted by agntz.co or your own
+self-hosted TS deployment. The Python package continues to support embedded
+local execution, stores, resources, and memrez for in-process applications.
+
+## Memrez
+
+The Python package includes namespace grants, the memrez core, memory resource
+provider wiring, and in-memory/SQLite/Postgres memory stores. By default,
+`create_memrez()` wires memrez's built-in LLM reasoner for tagging and
+curation through direct LiteLLM calls. Install `agntz[litellm]` and set the
+provider key for the default model, such as `OPENAI_API_KEY`, when you want
+the default reasoner to run locally. Pass `DeterministicReasoner()` for tests
+or no-LLM kill-switch behavior.
+
+```python
+from agntz import LiteLLMModelProvider, agntz
+from agntz.resources.memrez import SqliteMemoryStore, create_memrez
+
+memrez = create_memrez(store=SqliteMemoryStore("./memory.db"))
+
+client = agntz(
+    agents="./agents",
+    resources={"memory": memrez.provider()},
+    model_provider=LiteLLMModelProvider(),
+)
+
+client.agents.run(
+    agent_id="support-with-memory",
+    input="Remember that I prefer metric units.",
+    context=["app/user/u_123"],
+)
+```
+
+You can also use memrez directly:
+
+```python
+memrez.write(["app/user/u_123"], "Prefers metric units.", topics_hint=["prefs"])
+entries = memrez.read(["app/user/u_123"], "prefs")
+```
+
+Configure invoke-time preload in the resource declaration. Topic taxonomy and
+reasoner policy belong to Memrez-level configuration, not the agent manifest:
+
+```yaml
+resources:
+  memory:
+    kind: memory
+    mode: read-write
+    preload:
+      core: true
+      topics: [goals, equipment]
+      limit: 30
+      maxChars: 10000
+      types: [fact, preference, summary]
+```
+
+Override the reasoner explicitly when needed:
+
+```python
+from agntz.resources.memrez import (
+    DeterministicReasoner,
+    ReasonerModelConfig,
+    create_memrez,
+    llm_reasoner,
+)
+
+memrez = create_memrez(
+    reasoner=llm_reasoner(
+        tagger_model=ReasonerModelConfig(provider="anthropic", name="claude-haiku-4-5")
+    )
+)
+
+test_memrez = create_memrez(reasoner=DeterministicReasoner())
+```
+
+## CLI
+
+The terminal CLI is distributed through the Node package `@agntz/sdk`, while
+Python service code uses the `agntz` Python package.
+
+```bash
+npx @agntz/sdk create "Answer support questions in a concise tone" -o ./agents/support.yaml
+npx @agntz/sdk run ./agents/support.yaml --input '{"userQuery":"hello"}'
+npx @agntz/sdk --help
+```
+
+Use Python code when the agent needs Python local tools, a Python resource
+provider, or a Python store. The same YAML file can be loaded by both runtimes.
+
+## Current parity
+
+Implemented in this package:
+
+- Hosted sync and async clients for agents, versions, aliases, run, run stream,
+  async runs, traces, datasets, evals, eval runs, cancellation, and eval scores.
+- Local YAML execution for `llm`, `tool`, `sequential`, and `parallel` agents.
+- Local Python tools, HTTP tools, MCP JSON-RPC tools, and agent-as-tool calls.
+- Versioned local and hosted agent resolution for bare ids, `@latest`, exact
+  timestamps, and aliases.
+- First-class datasets, eval definitions, eval runs, and latest-score tracking.
+- Runtime namespace grants, resource providers, and the memrez memory provider.
+- Memrez LLM reasoner default, preload/topic policy, in-memory, SQLite, and
+  Postgres memory stores.
+- LiteLLM-backed model execution with tool-call loop support.
+- Memory, SQLite, and Postgres stores for local data including runs,
+  traces, sessions, agent versions, aliases, eval data, latest scores, and API
+  keys and namespace roots.
+- Import surfaces for agents, sessions, and memory use Pythonic `import_`
+  methods on local and hosted clients.
+- Contract fixtures shared with the TypeScript core manifest runtime.
+
+Still intentionally outside this first Python package slice:
+
+- The hosted product UI remains TypeScript.
+- Terminal eval commands remain in the Node CLI.
+- 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
+```