Metadata-Version: 2.4
Name: tellodb
Version: 0.1.3
Summary: Python SDK for Tellodb: The cognitive memory engine for AI agents with fact supersession, knowledge graphs, and temporal truth retrieval.
Author-email: Sharjeel Abbas <sharjeel@tellodb.com>
License: MIT
Project-URL: Homepage, https://tellodb.com
Project-URL: Documentation, https://tellodb.com/docs
Project-URL: Blog, https://tellodb.com/blog
Project-URL: Benchmarks, https://tellodb.com/platform/benchmarks
Project-URL: Signup, https://tellodb.com/signup
Project-URL: Source Code, https://github.com/tellodb/tellodb
Keywords: memory,retrieval,sdk,temporal-memory,tellodb,ai-agents,knowledge-graph,vector-search
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Tellodb Python SDK

The official Python client for [Tellodb](https://tellodb.com), the cognitive memory engine for AI agents with fact supersession, knowledge graphs, and temporal truth retrieval.

This SDK wraps both the local-first Rust memory engine sidecar and the hosted/remote HTTP API under the exact same interface, ensuring a seamless development loop from local testing to cloud deployment.

---

## Core Features

- **Fact Supersession & Conflict Resolution**: Automatically manages evolving facts. When a new memory conflicts with an old one (e.g. *"I moved to Seattle"* superseding *"I live in Austin"*), the engine invalidates the old memory, resolving conflict and preventing hallucinations.
- **Hybrid Vector & Lexical Retrieval**: Unifies HNSW semantic vector embeddings, BM25 full-text keyword matching, and neural rerankers for high-precision recall.
- **Temporal Querying & Decay**: Apply time-aware relevance decay (freshness biasing) or query specific time windows to answer what was true at a specific moment.
- **Knowledge Graph Memories**: Store memories alongside entity relations (`subject` ➔ `relation` ➔ `object`) and run walking traversals to fetch context networks.
- **Zero-Dependency Local Engine**: The SDK can download, resolve, run, and manage a local Rust memory engine sidecar binary. Run memory completely privately on your local machine.

---

## Installation

```bash
pip install tellodb
```

---

## Client Connection

Initialize one client per process and reuse it across requests to optimize connection pooling.

### 1. Local-First Development Flow
In local-first mode, the SDK handles the lifecycle of the Rust sidecar engine binary.

```python
from tellodb import TellodbClient

# Automatically resolves, downloads, and runs the Rust engine binary on startup
client = TellodbClient.from_local(
    auto_start=True,
    port=3000,
    data_dir="~/.tellodb/data",
)
```

### 2. Cloud Flow
Connect to the hosted Tellodb cloud platform or a self-hosted remote instance.

```python
from tellodb import TellodbClient

client = TellodbClient.from_cloud(
    base_url="https://engine.tellodb.com",
    api_key="your_tellodb_api_key",
)
```

---

## Usage Guide & Code Examples

### 1. Ingestion & Semantic Query
Store a natural language observation and search it semantically.

```python
# Ingest memory
client.ingest(
    entity_id="user-123",
    text="I prefer pour-over coffee to espresso.",
)

# Retrieve context with semantic query
hits = client.query(
    query="What kind of coffee do I like?",
    entity_id="user-123",
    top_k=5,
    rerank=True,
)

for hit in hits:
    print(f"[{hit.similarity:.3f}] {hit.textual_content} (ID: {hit.memory_id})")
```

### 2. Knowledge Graph & Relation Mapping
Store facts associated with semantic relations and traverse the memory graph.

```python
# Ingest memory with explicit graph relations
client.ingest(
    entity_id="user-123",
    text="Alice works at Tellodb.",
    relations=[("Alice", "works_at", "Tellodb")]
)

# Query immediate relations of a subject node
graph_res = client.graph_query(
    subject="Alice",
    edge_type="works_at",
)
print("Relations:", graph_res)

# Traverse the memory graph with a deep walk
walk_res = client.graph_walk(
    node="Alice",
    direction="out",
    depth=2,
    limit=20,
)
print("Walk Path:", walk_res)

# Export subgraph for custom visualizations
subgraph = client.export_graph(
    seed="Alice",
    max_nodes=50,
)
```

### 3. Temporal Queries
Enforce strict Unix millisecond boundaries to retrieve memories from a specific time window.

```python
# Find what was discussed during a specific time interval
window_hits = client.temporal_query(
    entity_id="user-123",
    textual_query="Where did I work?",
    window_start_ms=1700000000000,  # Nov 2023
    window_end_ms=1760000000000,    # Oct 2025
)
print("Windowed memories:", window_hits)
```

### 4. Batch Ingestion
For high-throughput data loads, ingest items in batch chunks.

```python
from tellodb import IngestItem

items = [
    IngestItem(
        entity_id="user-123",
        text="I am learning Rust.",
        kind="Skill",
    ),
    IngestItem(
        entity_id="user-123",
        text="I want to build web apps.",
        kind="Goal",
    ),
]

client.ingest_many(items, batch_size=64)
```

### 5. Memory Inspection & Self-Repair Deletion
Inspect raw memory state and safely delete nodes while triggering automatic predecessor recovery.

```python
memory_id = "user-123::sdk::example_id"

# Inspect memory details and surrounding context turn-window
details = client.inspect_memory(
    memory_id=memory_id,
    include_turn_window=True,
    turn_window_radius=3,
)
print("Memory detail:", details)

# Delete memory (safely updates slots and heals invalidated facts)
client.delete_memory(
    memory_id=memory_id,
    reason="User requested removal",
)
```

### 6. Analytics Querying
Perform deterministic aggregate analytics on metric tags.

```python
analytics = client.analytics_query(
    entity_id="user-123",
    label="coffee_intake",
    start_timestamp_ms=1700000000000,
)
print("Analytics trend:", analytics)
```

---

## Engine Binary Resolution
When calling `TellodbClient.from_local()`, the engine resolves the path to the local Rust sidecar binary in the following priority order:

1. Explicitly provided `binary_path` argument.
2. `TELLODB_ENGINE_BINARY` or `TEMPORAL_MEMORY_ENGINE_BINARY` environment variables.
3. Repo-local builds: `target/release/temporal_memory` or `target/debug/temporal_memory`.
4. Cached binaries in `TELLODB_ENGINE_CACHE_DIR`.
5. Automatic download from `TELLODB_ENGINE_MANIFEST_URL`.

---

## Environment Configuration
The SDK configures the Rust engine binary using the following variables:

- `TEMPORAL_MEMORY_HOST`: Network interface host (default: `127.0.0.1`).
- `TEMPORAL_MEMORY_PORT`: Network interface port (default: `3000`).
- `TEMPORAL_MEMORY_DATA_DIR`: Directory where data files are persisted.
- `TEMPORAL_MEMORY_API_KEY`: API credential key for the local instance.
- `TELLODB_API_KEY`: API credential key for the remote/cloud client.
