Metadata-Version: 2.4
Name: agentics-you
Version: 1.2.1
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

```bash
pip install agentics-you
```

[agentics-you on PyPI](https://pypi.org/project/agentics-you/)

```bash
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()  # reads AGENTICS_API_KEY
client.memories.add("Dana prefers aisle seats.", wait=True)
```

## 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` (1.2.1 is live: <https://pypi.org/project/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.1
git push origin sdk-py-v1.2.1
```

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. Trusted publishing for this repo is already set at <https://pypi.org/manage/account/publishing/> (workflow `pypi-publish.yml`, environment `pypi`).

## Links

- PyPI: <https://pypi.org/project/agentics-you/>
- 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
