Metadata-Version: 2.4
Name: seam-client
Version: 2.0.0
Summary: Public Python SDK for building agents with SEAM memory
Author: BlackhatShiftey
License-Expression: Apache-2.0
Project-URL: Homepage, https://canticle.cc
Project-URL: Documentation, https://github.com/BlackhatShiftey/Seam_Runtime/tree/main/sdk
Project-URL: Repository, https://github.com/BlackhatShiftey/Seam_Runtime
Project-URL: Issues, https://github.com/BlackhatShiftey/Seam_Runtime/issues
Keywords: ai,agents,memory,sdk,seam
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: ruff<1,>=0.6; extra == "test"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# seam-client

Build custom agents with SEAM-backed long-term memory without embedding the
private SEAM runtime in your application.

`seam-client` is the public, Apache-2.0 Python SDK. It provides:

- synchronous and asynchronous clients
- `remember`, `recall`, and context assembly
- a framework-neutral prepare/complete turn lifecycle
- inspectable rendered context and opaque recalled-memory metadata
- typed, opaque response models
- bearer-token authentication and explicit error types

It does **not** contain the private SEAM runtime, MIRL implementation, HS/1
surface codecs, storage engine, ranking logic, benchmark holdouts, or model
orchestration internals.

## Install

```bash
python -m pip install seam-client
```

Version 2.0.0 adds the structured agent-turn lifecycle. To install directly
from the public source repository instead:

```bash
python -m pip install \
  "seam-client @ git+https://github.com/BlackhatShiftey/Seam_Runtime.git@main#subdirectory=sdk"
```

## Use it in an agent

```python
from seam_client import AgentMemory, SeamClient

client = SeamClient(
    base_url="http://127.0.0.1:8765",
    api_key="your-seam-token",
)
memory = AgentMemory(
    client=client,
    namespace="research-agent",
    session_id="thread-42",
    agent_id="researcher",
)

messages = [{"role": "user", "content": "What did we decide about licensing?"}]
turn = memory.prepare_turn(
    messages,
    user_input=messages[-1]["content"],
)

# Call your preferred model/provider with `turn.messages`.
assistant_output = "We separated the public SDK from the private runtime."

receipt = memory.complete_turn(turn, assistant_output)
```

`AgentMemory` does not choose or call a model. It supplies memory hooks that can
wrap your own OpenAI, Anthropic, local-model, or custom agent loop.

`turn.context` contains the rendered context. `turn.memories` contains the
typed, opaque memory records behind it, so an agent can log scores or build
citations without access to SEAM internals. `prepare_turn` copies the supplied
message mappings and never mutates the caller's list.

Use `memory_query=` when the best retrieval query differs from the raw user
input:

```python
turn = memory.prepare_turn(
    messages,
    user_input="Compare those approaches.",
    memory_query="licensing architecture alternatives",
)
```

The 0.1 hooks remain available: `before_turn`, `after_turn`,
`system_message`, and `augment_messages`.

## Direct client

```python
from seam_client import SeamClient

with SeamClient.from_env() as seam:
    seam.remember(
        "The operator prefers evidence-backed answers.",
        namespace="my-agent",
        session_id="thread-42",
    )
    recalled = seam.recall(
        "answer style",
        namespace="my-agent",
        session_id="thread-42",
    )
    for memory in recalled.memories:
        print(memory.text, memory.score)
```

Environment variables:

- `SEAM_BASE_URL` — defaults to `http://127.0.0.1:8765`
- `SEAM_API_TOKEN` — optional bearer token for the configured server

## Async client

```python
from seam_client import AsyncAgentMemory, AsyncSeamClient

async with AsyncSeamClient.from_env() as client:
    memory = AsyncAgentMemory(
        client=client,
        namespace="async-agent",
        session_id="thread-7",
    )
    turn = await memory.prepare_turn(
        [{"role": "user", "content": "What should I remember?"}],
        user_input="What should I remember?",
    )
    # assistant_output = await your_model(turn.messages)
    # await memory.complete_turn(turn, assistant_output)
```

## Partitions

- `namespace` isolates one agent or application from another.
- `session_id` isolates a specific conversation or run.
- `scope` is semantic and defaults to `thread`. Supported server scopes are
  `ephemeral`, `global`, `org`, `project`, `thread`, and `user`.

The server maps public partitions into an SDK-only internal namespace. Public
responses use opaque `rcpt_...` and `mem_...` identifiers.

## Hosted access

The SDK is public. A hosted SEAM endpoint is not implied by installing it.
Use a SEAM server URL and token you have been given, or run an authorized local
SEAM server. Hosted access remains separately provisioned.
