agentics-you 1.2.0__tar.gz

agentics_you-1.2.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: agentics-you
+Version: 1.2.0
+Summary: Agentics SDK for Python: shared memory for AI agents, receipts and the gateway.
+Author-email: Agentics Technologies LLC <hello@agentics.you>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://agentics.you
+Project-URL: Documentation, https://agentics.you/developers/
+Project-URL: Source, https://github.com/agenticstechnologies/agentics.you/tree/master/sdks/python
+Keywords: agentics,memory,agents,mcp,llm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.0.3; extra == "openai"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == "litellm"
+
+# agentics-you — Python SDK
+
+The Python SDK for **[Agentics](https://agentics.you)**: shared memory for AI agents, with a receipt for every write. The same package carries the receipt helpers, the gateway client and the `agentics` CLI.
+
+## Install
+
+> **Not yet published.** `agentics-you` is not on PyPI, so these installs fail. Install from a checkout of this repo with `pip install ./sdks/python`. To call the memory API today without it, use the [REST API](https://agentics.you/docs/api/) or the hosted MCP server at `https://agentics.you/mcp`.
+
+```bash
+pip install agentics-you
+pip install "agentics-you[openai]"    # + OpenAI Agents SDK trace processor (agentics_you.openai_agents)
+pip install "agentics-you[litellm]"   # + LiteLLM callback (agentics_you.litellm_callback)
+```
+
+The import name is `agentics_you`. `agentics` on PyPI belongs to another publisher.
+
+## Quickstart
+
+```python
+from agentics_you import AgenticsClient
+client = AgenticsClient()  # AGENTICS_API_KEY=ak_...
+client.memories.add("Dana prefers aisle seats.", wait=True)
+hits = client.memories.search("Which seat does Dana want?")["hits"]
+```
+
+## Memory in more detail
+
+Create an org API key (`ak_...`) in the console under API Keys.
+
+```bash
+export AGENTICS_API_KEY=ak_...
+export AGENTICS_AGENT=...   # optional: agent identity token, so writes are attributed to that agent
+```
+
+```python
+from agentics_you import AgenticsClient
+
+client = AgenticsClient()
+
+# Write. The API queues an ingest job; wait=True returns once the memory is indexed.
+r = client.memories.add("Dana prefers aisle seats on flights over two hours.",
+                        metadata={"topic": "travel"}, wait=True)
+
+# Recall. Each hit carries score, why and receipt_hash.
+hits = client.memories.search("Which seat does Dana want?", k=5)["hits"]
+
+client.memories.get(r["memory_id"])
+client.memories.list(limit=20)
+client.memories.delete(r["memory_id"])
+```
+
+| Resource | Methods | Route |
+|---|---|---|
+| `client.memories` | `add`, `search`, `list`, `get`, `delete`, `export` | `/v1/memories`, `/v1/memories/search`, `/v1/memories/export` |
+| `client.namespaces` | `list`, `create`, `get`, `rename`, `delete` | `/v1/namespaces` |
+| `client.ingest` | `get`, `list`, `retry`, `wait` | `/v1/ingest`, `/v1/ingest/{job_id}` |
+
+`AsyncAgenticsClient` has the same methods as coroutines. Errors are typed by status: `ValidationError` (400/413/422), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `ServerError` (5xx), all subclasses of `AgenticsError` with `code`, `status` and `details`. Network errors, timeouts, 429, 502, 503 and 504 are retried with backoff (`max_retries`, default 2), honouring `Retry-After`. `AGENTICS_BASE_URL` points the client at another deployment. Stdlib only, Python 3.9+.
+
+## Receipts (decorator)
+
+```python
+from agentics_you import Network
+
+net = Network(api_key="ak_...")
+
+@net.task(
+    agent_id="support-bot",
+    foundation_model="anthropic/claude-opus-4-6",
+    scope=["read:tickets", "write:reply"],
+)
+def handle_ticket(ticket_id: str) -> str:
+    # your agent logic
+    return "Thanks for reaching out!"
+
+reply = handle_ticket("abc-123")
+# A receipt was recorded.
+```
+
+## Receipts (context manager)
+
+```python
+from agentics_you import Agentics
+
+agentics = Agentics(api_key="ak_...")
+
+with agentics.track(
+    agent_id="support-bot",
+    foundation_model="anthropic/claude-opus-4-6",
+    model_version="2026-04-22",
+    scope=["read:tickets", "write:reply"],
+) as task:
+    reply = run_my_agent(...)
+    task.set_outputs(reply)
+    task.set_outcome("success")
+```
+
+## Gateway — drop-in OpenAI-compatible client
+
+Change **one** `base_url` and keep your existing OpenAI/Anthropic SDK. Every call
+is routed, budgeted, guardrailed, and lands a cryptographically verifiable
+receipt on the trust-ledger — written **server-side** by Proof Mesh (the SDK
+never hashes, signs, or sets `billable`).
+
+```python
+from openai import OpenAI                  # your existing SDK, unchanged
+from agentics_you import createHeaders
+
+client = OpenAI(
+    base_url="https://agentics.you/api/v1",   # the only change
+    api_key="ak_...",                              # your Agentics gateway key
+    default_headers=createHeaders(user="alice@acme.com",
+                                  metadata={"cost_center": "support"}),
+)
+resp = client.chat.completions.create(
+    model="@anthropic/claude-opus-4-8",
+    messages=[{"role": "user", "content": "hi"}],
+)
+```
+
+Or use the self-contained client (stdlib only, no `openai` needed):
+
+```python
+from agentics_you import AgenticsGateway
+
+gw = AgenticsGateway(base_url="https://agentics.you/api/v1", api_key="ak_...")
+resp = gw.with_options(user="alice@acme.com").chat.completions.create(
+    model="@anthropic/claude-opus-4-8",
+    messages=[{"role": "user", "content": "hi"}],
+)
+
+# Auto-instrument CrewAI / LangGraph, or attach LangChain/LlamaIndex handlers:
+from agentics_you import LangchainCallbackHandler
+chain.invoke(x, config={"callbacks": [LangchainCallbackHandler(user="alice@acme.com")]})
+
+# Browse the Model Garden catalog:
+gw.list_models(provider="anthropic")
+```
+
+`createHeaders()` emits the frozen `x-agentics-{trace-id,span-id,user,meta,debug}`
+header set; these become the parent receipt's identity fields, so per-user
+attribution and provable savings start at your call site. Full quickstart:
+<https://agentics.you/docs/sdk/python.html>.
+
+## Authentication
+
+The SDK looks for an API key in this order:
+
+1. `api_key=` constructor argument
+2. `AGENTICS_API_KEY` environment variable
+3. `~/.agentics/credentials` (set by `agentics login --api-key ak_...`)
+
+Issue API keys from the dashboard at <https://agentics.you/dashboard/api-keys>.
+
+## CLI
+
+```bash
+# Save credentials
+agentics login --api-key ak_...
+
+# Register / update an agent from a manifest
+cat > agentics.json <<EOF
+{
+  "display_name": "Support Bot",
+  "handle": "support-bot",
+  "foundation_model": "anthropic/claude-opus-4-6",
+  "scope_array": ["read:tickets", "write:reply"],
+  "description": "Handles tier-1 support tickets"
+}
+EOF
+agentics deploy
+
+# Or override fields inline
+agentics deploy --name "Support Bot" --model anthropic/claude-opus-4-6 \\
+                --scope "read:tickets,write:reply"
+
+# Inspect your account
+agentics whoami
+agentics agents
+
+# Gateway devex verbs
+agentics gateway test --url https://agentics.you/api/v1 --user alice@acme.com
+agentics config validate gateway-config.json
+agentics config publish  gateway-config.json --name default
+agentics prompt push     support-greeting.json
+agentics log tail --limit 5            # gateway receipts with their trace_id
+agentics proof verify    <receipt_hash>  # 4-step end-to-end verify
+agentics proof bundle    <receipt_hash>  # offline-verifiable evidence bundle
+agentics models --provider anthropic
+```
+
+## Publishing (for maintainers)
+
+Published from `sdks/python/` to PyPI as `agentics-you` by `.github/workflows/pypi-publish.yml`, with PyPI Trusted Publishing (OIDC, no token on this repo):
+
+```bash
+# Bump version in pyproject.toml and agentics_you/version.py, then tag sdk-py-v<semver>.
+git tag sdk-py-v1.2.0
+git push origin sdk-py-v1.2.0
+```
+
+The action runs the unit tests, writes the tag's version into both version files, builds the sdist and wheel, runs `twine check`, and publishes. One-time: add this repo as a trusted publisher for `agentics-you` at <https://pypi.org/manage/account/publishing/> (workflow `pypi-publish.yml`, environment `pypi`).
+
+## Links
+
+- Marketing site & docs: <https://agentics.you>
+- Status & dashboards: <https://agentics.you/intelligence/>
+- Live public ledger: <https://agentics.you/ledger/>
+- File a bug: <https://github.com/agenticstechnologies/agentics.you/issues>
+
+Apache-2.0

agentics_you-1.2.0/README.md

@@ -0,0 +1,211 @@
+# agentics-you — Python SDK
+
+The Python SDK for **[Agentics](https://agentics.you)**: shared memory for AI agents, with a receipt for every write. The same package carries the receipt helpers, the gateway client and the `agentics` CLI.
+
+## Install
+
+> **Not yet published.** `agentics-you` is not on PyPI, so these installs fail. Install from a checkout of this repo with `pip install ./sdks/python`. To call the memory API today without it, use the [REST API](https://agentics.you/docs/api/) or the hosted MCP server at `https://agentics.you/mcp`.
+
+```bash
+pip install agentics-you
+pip install "agentics-you[openai]"    # + OpenAI Agents SDK trace processor (agentics_you.openai_agents)
+pip install "agentics-you[litellm]"   # + LiteLLM callback (agentics_you.litellm_callback)
+```
+
+The import name is `agentics_you`. `agentics` on PyPI belongs to another publisher.
+
+## Quickstart
+
+```python
+from agentics_you import AgenticsClient
+client = AgenticsClient()  # AGENTICS_API_KEY=ak_...
+client.memories.add("Dana prefers aisle seats.", wait=True)
+hits = client.memories.search("Which seat does Dana want?")["hits"]
+```
+
+## Memory in more detail
+
+Create an org API key (`ak_...`) in the console under API Keys.
+
+```bash
+export AGENTICS_API_KEY=ak_...
+export AGENTICS_AGENT=...   # optional: agent identity token, so writes are attributed to that agent
+```
+
+```python
+from agentics_you import AgenticsClient
+
+client = AgenticsClient()
+
+# Write. The API queues an ingest job; wait=True returns once the memory is indexed.
+r = client.memories.add("Dana prefers aisle seats on flights over two hours.",
+                        metadata={"topic": "travel"}, wait=True)
+
+# Recall. Each hit carries score, why and receipt_hash.
+hits = client.memories.search("Which seat does Dana want?", k=5)["hits"]
+
+client.memories.get(r["memory_id"])
+client.memories.list(limit=20)
+client.memories.delete(r["memory_id"])
+```
+
+| Resource | Methods | Route |
+|---|---|---|
+| `client.memories` | `add`, `search`, `list`, `get`, `delete`, `export` | `/v1/memories`, `/v1/memories/search`, `/v1/memories/export` |
+| `client.namespaces` | `list`, `create`, `get`, `rename`, `delete` | `/v1/namespaces` |
+| `client.ingest` | `get`, `list`, `retry`, `wait` | `/v1/ingest`, `/v1/ingest/{job_id}` |
+
+`AsyncAgenticsClient` has the same methods as coroutines. Errors are typed by status: `ValidationError` (400/413/422), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `ServerError` (5xx), all subclasses of `AgenticsError` with `code`, `status` and `details`. Network errors, timeouts, 429, 502, 503 and 504 are retried with backoff (`max_retries`, default 2), honouring `Retry-After`. `AGENTICS_BASE_URL` points the client at another deployment. Stdlib only, Python 3.9+.
+
+## Receipts (decorator)
+
+```python
+from agentics_you import Network
+
+net = Network(api_key="ak_...")
+
+@net.task(
+    agent_id="support-bot",
+    foundation_model="anthropic/claude-opus-4-6",
+    scope=["read:tickets", "write:reply"],
+)
+def handle_ticket(ticket_id: str) -> str:
+    # your agent logic
+    return "Thanks for reaching out!"
+
+reply = handle_ticket("abc-123")
+# A receipt was recorded.
+```
+
+## Receipts (context manager)
+
+```python
+from agentics_you import Agentics
+
+agentics = Agentics(api_key="ak_...")
+
+with agentics.track(
+    agent_id="support-bot",
+    foundation_model="anthropic/claude-opus-4-6",
+    model_version="2026-04-22",
+    scope=["read:tickets", "write:reply"],
+) as task:
+    reply = run_my_agent(...)
+    task.set_outputs(reply)
+    task.set_outcome("success")
+```
+
+## Gateway — drop-in OpenAI-compatible client
+
+Change **one** `base_url` and keep your existing OpenAI/Anthropic SDK. Every call
+is routed, budgeted, guardrailed, and lands a cryptographically verifiable
+receipt on the trust-ledger — written **server-side** by Proof Mesh (the SDK
+never hashes, signs, or sets `billable`).
+
+```python
+from openai import OpenAI                  # your existing SDK, unchanged
+from agentics_you import createHeaders
+
+client = OpenAI(
+    base_url="https://agentics.you/api/v1",   # the only change
+    api_key="ak_...",                              # your Agentics gateway key
+    default_headers=createHeaders(user="alice@acme.com",
+                                  metadata={"cost_center": "support"}),
+)
+resp = client.chat.completions.create(
+    model="@anthropic/claude-opus-4-8",
+    messages=[{"role": "user", "content": "hi"}],
+)
+```
+
+Or use the self-contained client (stdlib only, no `openai` needed):
+
+```python
+from agentics_you import AgenticsGateway
+
+gw = AgenticsGateway(base_url="https://agentics.you/api/v1", api_key="ak_...")
+resp = gw.with_options(user="alice@acme.com").chat.completions.create(
+    model="@anthropic/claude-opus-4-8",
+    messages=[{"role": "user", "content": "hi"}],
+)
+
+# Auto-instrument CrewAI / LangGraph, or attach LangChain/LlamaIndex handlers:
+from agentics_you import LangchainCallbackHandler
+chain.invoke(x, config={"callbacks": [LangchainCallbackHandler(user="alice@acme.com")]})
+
+# Browse the Model Garden catalog:
+gw.list_models(provider="anthropic")
+```
+
+`createHeaders()` emits the frozen `x-agentics-{trace-id,span-id,user,meta,debug}`
+header set; these become the parent receipt's identity fields, so per-user
+attribution and provable savings start at your call site. Full quickstart:
+<https://agentics.you/docs/sdk/python.html>.
+
+## Authentication
+
+The SDK looks for an API key in this order:
+
+1. `api_key=` constructor argument
+2. `AGENTICS_API_KEY` environment variable
+3. `~/.agentics/credentials` (set by `agentics login --api-key ak_...`)
+
+Issue API keys from the dashboard at <https://agentics.you/dashboard/api-keys>.
+
+## CLI
+
+```bash
+# Save credentials
+agentics login --api-key ak_...
+
+# Register / update an agent from a manifest
+cat > agentics.json <<EOF
+{
+  "display_name": "Support Bot",
+  "handle": "support-bot",
+  "foundation_model": "anthropic/claude-opus-4-6",
+  "scope_array": ["read:tickets", "write:reply"],
+  "description": "Handles tier-1 support tickets"
+}
+EOF
+agentics deploy
+
+# Or override fields inline
+agentics deploy --name "Support Bot" --model anthropic/claude-opus-4-6 \\
+                --scope "read:tickets,write:reply"
+
+# Inspect your account
+agentics whoami
+agentics agents
+
+# Gateway devex verbs
+agentics gateway test --url https://agentics.you/api/v1 --user alice@acme.com
+agentics config validate gateway-config.json
+agentics config publish  gateway-config.json --name default
+agentics prompt push     support-greeting.json
+agentics log tail --limit 5            # gateway receipts with their trace_id
+agentics proof verify    <receipt_hash>  # 4-step end-to-end verify
+agentics proof bundle    <receipt_hash>  # offline-verifiable evidence bundle
+agentics models --provider anthropic
+```
+
+## Publishing (for maintainers)
+
+Published from `sdks/python/` to PyPI as `agentics-you` by `.github/workflows/pypi-publish.yml`, with PyPI Trusted Publishing (OIDC, no token on this repo):
+
+```bash
+# Bump version in pyproject.toml and agentics_you/version.py, then tag sdk-py-v<semver>.
+git tag sdk-py-v1.2.0
+git push origin sdk-py-v1.2.0
+```
+
+The action runs the unit tests, writes the tag's version into both version files, builds the sdist and wheel, runs `twine check`, and publishes. One-time: add this repo as a trusted publisher for `agentics-you` at <https://pypi.org/manage/account/publishing/> (workflow `pypi-publish.yml`, environment `pypi`).
+
+## Links
+
+- Marketing site & docs: <https://agentics.you>
+- Status & dashboards: <https://agentics.you/intelligence/>
+- Live public ledger: <https://agentics.you/ledger/>
+- File a bug: <https://github.com/agenticstechnologies/agentics.you/issues>
+
+Apache-2.0

agentics_you-1.2.0/agentics_you/__init__.py

@@ -0,0 +1,82 @@
+"""agentics-you — the Agentics Python SDK: shared memory for AI agents, receipts and the gateway.
+
+Memory quickstart:
+
+    from agentics_you import AgenticsClient
+
+    client = AgenticsClient()                  # reads AGENTICS_API_KEY (ak_...), optional AGENTICS_AGENT
+    client.memories.add("Dana prefers aisle seats.", wait=True)
+    hits = client.memories.search("Which seat does Dana want?", k=5)["hits"]
+
+Receipts (decorator style):
+
+    from agentics_you import Network
+
+    net = Network(api_key="ak_...")
+
+    @net.task(scope=["read:tickets", "write:reply"])
+    def handle_ticket(ticket_id: str) -> str:
+        return reply
+
+Extras: ``agentics-you[openai]`` (agentics_you.openai_agents trace processor) and ``agentics-you[litellm]``
+(agentics_you.litellm_callback).
+"""
+from .client import Agentics, Task, TaskContext
+from .network import Network
+from .version import __version__
+
+# Memory client (namespaces, memories, ingest) with typed errors and retries.
+from .memory import (
+    AgenticsClient,
+    AsyncAgenticsClient,
+    AgenticsError,
+    ValidationError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    ServerError,
+)
+
+# Task receipts posted to /v1/receipts (formerly packages/agentics-python).
+from .receipts import client, Client
+
+# Gateway client (drop-in OpenAI-compatible base_url swap). Stdlib-only, so this
+# import is always safe even without the `openai` package installed.
+from .gateway import (
+    AgenticsGateway,
+    GatewayError,
+    createHeaders,
+    list_models,
+    DEFAULT_GATEWAY_BASE_URL,
+)
+
+__all__ = [
+    # Memory
+    "AgenticsClient", "AsyncAgenticsClient", "AgenticsError", "ValidationError", "AuthenticationError",
+    "PermissionDeniedError", "NotFoundError", "ConflictError", "RateLimitError", "ServerError",
+    # Receipts
+    "client", "Client",
+    "Agentics", "Task", "TaskContext",
+    "Network",
+    "AgenticsTasks", "AgenticsTasksError",
+    # Gateway (drop-in OpenAI-compatible client + trace/metadata propagation)
+    "AgenticsGateway", "GatewayError", "createHeaders", "list_models",
+    "DEFAULT_GATEWAY_BASE_URL",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    """Lazily expose the framework callback handlers so importing `agentics`
+    never requires LangChain/LlamaIndex/CrewAI to be installed."""
+    if name in ("AgenticsTasks", "AgenticsTasksError"):  # needs httpx, which is not a dependency
+        from . import tasks as _tasks
+
+        return getattr(_tasks, name)
+    if name in ("instrument", "LangchainCallbackHandler", "LlamaIndexCallbackHandler"):
+        from . import instrument as _instr
+
+        return getattr(_instr, name)
+    raise AttributeError(f"module 'agentics_you' has no attribute {name!r}")