Metadata-Version: 2.4
Name: seizn-memory
Version: 0.1.0
Summary: Memory middleware for AI NPCs - Python SDK for Seizn
Project-URL: Homepage, https://www.seizn.com
Project-URL: Documentation, https://www.seizn.com/docs
Project-URL: Repository, https://github.com/litheonhq/seizn-sdk-python
Project-URL: Changelog, https://github.com/litheonhq/seizn-sdk-python/blob/main/CHANGELOG.md
Author-email: Litheon LLC <dev@seizn.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,games,memory,middleware,npc,sdk,seizn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Seizn Python SDK

Python SDK for Seizn, the memory middleware layer for AI NPCs.

Use Seizn to persist what NPCs remember across sessions, shard world state by namespace, and retrieve the right context before each response.

[![PyPI version](https://badge.fury.io/py/seizn-memory.svg)](https://badge.fury.io/py/seizn-memory)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install seizn-memory
```

## Quick Start

```python
from seizn import MemoryType, SeizinClient

client = SeizinClient(api_key="szn_your_api_key")
village = client.namespace("smallgod-village-404")

village.add(
    content="NPC Mira remembers the god flooded the riverbank last spring.",
    memory_type=MemoryType.EXPERIENCE,
    importance=0.9,
    tags=["npc:mira", "event:flood", "faction:river-clan"],
)

village.add(
    content="River Clan distrusts lightning blessings after losing two elders.",
    memory_type=MemoryType.RELATIONSHIP,
    importance=0.8,
    tags=["faction:river-clan", "belief:storm", "god:fear"],
)

results = village.search(
    "Who still fears the flood?",
    tags=["event:flood"],
    limit=5,
)

for result in results:
    print(f"{result.score:.2f} :: {result.memory.content}")

client.close()
```

## What This SDK Covers Today

- add, update, list, search, and delete memories
- namespace-scoped memory flows per game, shard, save slot, or faction
- sync and async clients with typed models
- memory types for facts, preferences, experiences, relationships, and instructions

## Suggested NPC Modeling Pattern

Use namespaces to isolate game titles or environments:

- `smallgod-prod`
- `smallgod-staging`
- `npc-sim-seed-404`

Use tags to keep retrieval cheap and precise:

- `npc:<npc-id>`
- `faction:<faction-id>`
- `event:<event-id>`
- `family:<lineage-id>`
- `region:<zone-id>`

Recommended memory types:

- `fact`: stable world facts, roles, biographies
- `experience`: witnessed events, battles, disasters, blessings
- `relationship`: trust, fear, grudges, kinship
- `instruction`: behavior constraints, quest rules, taboo knowledge

## Async Usage

```python
import asyncio

from seizn import AsyncSeizinClient, MemoryType


async def main() -> None:
    async with AsyncSeizinClient(api_key="szn_your_api_key") as client:
        sim = client.namespace("npc-sim-seed-404")
        await sim.add(
            content="Blacksmith Toma trusts Mira after she shared food during the winter shortage.",
            memory_type=MemoryType.RELATIONSHIP,
            tags=["npc:toma", "npc:mira", "season:winter"],
        )

        results = await sim.search("Who does Toma trust?", tags=["npc:toma"])
        for result in results:
            print(result.memory.content)


asyncio.run(main())
```

## Environment Variables

Set your API key once:

```bash
export SEIZN_API_KEY=szn_your_api_key
```

Then initialize without passing it directly:

```python
from seizn import SeizinClient

client = SeizinClient()
```

## API Surface

### `SeizinClient`

```python
SeizinClient(
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 30.0,
)
```

Methods:

- `add(content, **options)`
- `search(query, **options)`
- `get(memory_id)`
- `update(memory_id, **options)`
- `delete(memory_id)`
- `list(**options)`
- `namespace(name)`
- `close()`

### `AsyncSeizinClient`

The async client mirrors the same methods with `await`.

## Error Handling

```python
from seizn import AuthenticationError, NotFoundError, RateLimitError, SeizinClient

client = SeizinClient(api_key="szn_your_api_key")

try:
    client.get("mem_missing")
except AuthenticationError as exc:
    print(f"Auth failed: {exc.message}")
except NotFoundError as exc:
    print(f"Missing memory: {exc.message}")
except RateLimitError as exc:
    print(f"Retry after {exc.retry_after}s")
```

## Development

```bash
pip install -e ".[dev]"
pytest
mypy src/seizn
ruff check src tests
```

## Links

- Homepage: https://www.seizn.com
- Documentation: https://www.seizn.com/docs
- API reference: https://www.seizn.com/docs/api-reference
- Seizn app: https://www.seizn.com

## License

MIT License. See [LICENSE](LICENSE).
