Metadata-Version: 2.4
Name: tetramem-sdk
Version: 1.0.0
Summary: Python SDK for the Epicode API — spatial AI memory system
Author-email: sunormesky-max <sunorme@163.com>
License: MIT
Project-URL: Homepage, https://epicode.cn
Project-URL: Documentation, https://github.com/sunormesky-max/epicode/tree/main/backend/sdk/python
Project-URL: Repository, https://github.com/sunormesky-max/epicode
Project-URL: Issues, https://github.com/sunormesky-max/epicode/issues
Keywords: epicode,ai,memory,vector,knowledge-graph,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# Epicode SDK for Python

Python client library for the Epicode API.

## Installation

```bash
pip install tetramem-sdk
```

## Quick Start

```python
from tetramem import EpicodeClient

client = EpicodeClient("your-api-key")

# Store a memory
mem = client.remember("The project deadline is June 15.")
print(mem.id, mem.labels)

# Search memories
results = client.search("deadline", limit=5)
for r in results.results:
    print(r.content, r.similarity)

# Recall associative memories
recall = client.recall("project timeline", depth=3)
print(recall.seed_count, recall.emotion.pleasure)

# Ask a question
answer = client.ask("When is the deadline?")
print(answer.answer)

# Get account stats
stats = client.stats()
print(stats.memories_used, "/", stats.max_memories)

# Knowledge graph
node = client.create_node("Python 3.12 released", labels=["python", "release"])
node_data = client.get_node(node.id)
knowledge = client.knowledge(node.id)

# Timeline
tl = client.timeline()
print(tl.total, "events")

client.close()
```

## Context Manager

```python
with EpicodeClient("your-api-key") as client:
    health = client.health()
    print(health.status, health.version)
```

## Admin API

```python
from tetramem import EpicodeAdmin

admin = EpicodeAdmin("your-admin-key")

# Register a new user
user = admin.register("alice", plan="pro")
print(user.api_key, user.max_memories)

# List users
users = admin.list_users()
print(users.total_users, users.active_engines)

# Global stats
stats = admin.get_stats()
print(stats.max_users)

admin.close()
```

## Error Handling

```python
from tetramem import EpicodeClient, AuthenticationError, PlanLimitExceededError

client = EpicodeClient("invalid-key")

try:
    client.remember("test")
except AuthenticationError:
    print("Invalid API key")
except PlanLimitExceededError:
    print("Memory limit reached")
```

## Configuration

```python
client = EpicodeClient(
    "your-api-key",
    base_url="http://localhost:9111",  # default
    timeout=60,                                 # seconds, default 30
)
```

## Requirements

- Python >= 3.10
- requests >= 2.28
