Metadata-Version: 2.4
Name: yod
Version: 0.2.1
Summary: Web-based personal memory assistant backend (FastAPI + Neo4j + Qdrant + OpenAI)
License-File: LICENSE
Author: Yod
Author-email: support@yod.ai
Requires-Python: >=3.11,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: PyJWT[crypto] (>=2.10.0,<3.0.0)
Requires-Dist: authlib (==1.6.6)
Requires-Dist: fastapi (==0.120.1)
Requires-Dist: httpx (==0.27.2)
Requires-Dist: neo4j (==5.27.0)
Requires-Dist: openai (==1.59.6)
Requires-Dist: pydantic (==2.10.4)
Requires-Dist: pydantic-settings (==2.7.0)
Requires-Dist: python-multipart (==0.0.20)
Requires-Dist: qdrant-client (==1.12.1)
Requires-Dist: redis (>=5.0.0,<6.0.0)
Requires-Dist: starlette (==0.49.1)
Requires-Dist: tiktoken (==0.8.0)
Requires-Dist: uvicorn[standard] (==0.30.6)
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/yod-logo.png" alt="Yod">
  <p>
    <a href="https://yod.agames.live"><img alt="Demo" src="https://img.shields.io/badge/demo-yod.agames.live-111827?style=flat-square&labelColor=0b1220&color=111827"></a>
    <a href="https://pypi.org/project/yod/"><img alt="PyPI" src="https://img.shields.io/pypi/v/yod?style=flat-square&labelColor=0b1220&color=111827"></a>
    <a href="https://github.com/agames-live/yod-python"><img alt="SDK" src="https://img.shields.io/badge/SDK-yod--python-111827?style=flat-square&labelColor=0b1220&color=111827"></a>
    <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache_2.0-111827?style=flat-square&labelColor=0b1220&color=111827"></a>
  </p>
  <p>
    <a href="https://yod.agames.live"><img alt="Demo" src="https://img.shields.io/badge/▶_Demo-111827?style=for-the-badge&labelColor=0b1220&color=111827"></a>
    <a href="https://yod.agames.live/memory-demo.html"><img alt="System Architecture" src="https://img.shields.io/badge/▶_System_Architecture-14532d?style=for-the-badge&labelColor=14532d&color=14532d"></a>
  </p>
  <hr>
  <p><strong>Memory Infrastructure for AI Agents</strong></p>
  <p>Evidence-preserving memory with full citation provenance</p>
</div>

<br>

Yod extracts structured knowledge from conversations, stores it in a knowledge graph, and retrieves relevant context with **full citations**. Unlike memory systems that compress into summaries, Yod preserves the exact quotes that created each memory — enabling explainable AI.

<p align="center">
  <a href="https://yod.agames.live"><img src="assets/demo.png" alt="Yod Demo" width="450"></a>
</p>

## Why Yod?

| Feature | Yod | Mem0 | Notes |
|---------|-----|------|-------|
| **MERGE Operation** | ✅ ADD/UPDATE/DELETE/KEEP/MERGE | ⚠️ ADD/UPDATE/DELETE/NOOP | Yod can combine partial truths |
| **Citation Provenance** | ✅ Quote + Source links | ⚠️ Timestamps only | Yod traces to exact evidence |
| **PII Redaction** | ✅ Built-in | ❌ Not mentioned | Yod redacts before LLM/storage |
| **Quote Storage** | ✅ Exact quotes stored | ❌ No quote tracking | Yod preserves source evidence |
| Session Scoping | ✅ | ✅ | Both have user/agent/session |
| Temporal Queries | ✅ | ✅ (Mem0g) | Both support point-in-time |
| Enterprise Security | ⚠️ AES-256 | ✅ SOC2/HIPAA | Mem0 ahead on certifications |
| Multi-LLM Support | ✅ | ✅ | Both support multiple providers |
| **Self-Hosted Full Stack** | ✅ docker-compose | ⚠️ Cloud-first | Yod runs locally in 5 min |
| **Open Source Completeness** | ✅ Frontend + Auth + Deploy | ⚠️ Core only | Yod is fully open |

## Quick Start

### Cloud API

```bash
pip install yod
```

```python
from yod import YodClient

client = YodClient(api_key="sk-yod-...")  # Get a key at https://yod.agames.live

client.ingest_chat("My name is Alex. I work at Google.")
response = client.chat("Where do I work?")
print(response.answer)     # "You work at Google."
print(response.citations)  # [Citation(quote="I work at Google")]
```

### Self-Hosted

```bash
git clone https://github.com/agames-live/yod.git && cd yod
cp .env.example .env       # Add OPENAI_API_KEY
docker-compose up -d
```

Open http://localhost:3000 and sign in with Google/GitHub.

## Features

- **Evidence-Preserving** — Every memory links to the exact quote that created it
- **Smart Conflict Resolution** — LLM-based decisions: ADD, UPDATE, DELETE, KEEP, MERGE
- **Entity Resolution** — "my dog Max" links to the same entity across conversations
- **Temporal Versioning** — Query memories as they existed at any point in time
- **Session Scoping** — Isolate memories per conversation or agent
- **Multi-LLM** — OpenAI, Anthropic Claude, or local Ollama models
- **Full Stack** — Frontend, auth, and infrastructure configs included

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Yod API                              │
├──────────────────────────────┬──────────────────────────────┤
│     Ingest Pipeline          │       Query Pipeline         │
│  ┌────────────────────────┐  │  ┌─────────────────────────┐ │
│  │ Text → Semantic Chunks │  │  │ Semantic Search (Qdrant)│ │
│  │ LLM → Claims + Entities│  │  │ Graph Traversal (Neo4j) │ │
│  │ Conflict Resolution    │  │  │ Citation Assembly       │ │
│  │ Evidence Storage       │  │  │ LLM Response Generation │ │
│  └────────────────────────┘  │  └─────────────────────────┘ │
├──────────────────────────────┴──────────────────────────────┤
│  Neo4j (Graph)    │   Qdrant (Vectors)   │   Redis (Cache)  │
└─────────────────────────────────────────────────────────────┘
```

## Documentation

| Resource | Description |
|----------|-------------|
| [API Reference](docs/api/README.md) | Authentication, endpoints, rate limits |
| [Python SDK](sdk/README.md) | SDK guide with async support |
| [LLM Integrations](sdk/docs/integrations.md) | OpenAI, Anthropic, LangChain examples |
| [Configuration](docs/configuration.md) | LLM providers, sessions, memory settings |
| [Testing Guide](docs/testing-guide.md) | API testing with curl and SDK |

## Roadmap

| Feature | Status |
|---------|--------|
| Multi-LLM providers (OpenAI, Anthropic, Ollama) | ✅ Done |
| Session/Agent scoping | ✅ Done |
| LLM memory decisions (MERGE) | ✅ Done |
| Redis distributed caching | ✅ Done |
| TypeScript SDK | In Progress |
| SOC2/HIPAA certification | Planned |
| Framework integrations (CrewAI, LangGraph) | Planned |

## Development

```bash
# Backend
poetry install && uvicorn app.main:app --reload

# Frontend
cd frontend && npm install && npm run dev

# SDK
cd sdk && pip install -e ".[dev]" && pytest
```

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Priority areas:** TypeScript SDK, framework integrations (CrewAI, LangGraph, Vercel AI SDK)

## Chat Interface

<p align="center">
  <a href="https://yod.agames.live"><img src="assets/chat.png" alt="Yod Chat Interface" width="100%"></a>
</p>

## License

Apache 2.0 — See [LICENSE](LICENSE)

