Metadata-Version: 2.4
Name: mnemonexus
Version: 0.2.0
Summary: Cliente Python para mnemonexus — memória pra agentes de IA, open source, em português.
Project-URL: Homepage, https://github.com/lrdeoliveira/mnemonexus-python
Project-URL: Issues, https://github.com/lrdeoliveira/mnemonexus-python/issues
Author-email: Luciano Rodrigues de Oliveira <contato@redfoxcode.com.br>
License: MIT
License-File: LICENSE
Keywords: ai-agents,memory,mnemonexus,pgvector,rag
Classifier: Development Status :: 3 - Alpha
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# mnemonexus

[![PyPI version](https://img.shields.io/pypi/v/mnemonexus.svg)](https://pypi.org/project/mnemonexus/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mnemonexus.svg)](https://pypi.org/project/mnemonexus/)
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)

Cliente Python oficial para o [mnemonexus](https://github.com/lrdeoliveira/nexus-ai-memory) — memória pra agentes de IA, open source, em português.

Paridade com mem0 nas operações CRUD, mais o diferencial: **compilação Karpathy**, **twice-rule** pra lessons, **grafo de entidades**, **staleness/supersede** automáticos.

## Instalação

```bash
pip install mnemonexus
```

## Uso

```python
from mnemonexus import Nexus

nexus = Nexus(api_url="http://localhost:8080", token="seu-token-sanctum")

# Paridade mem0
nexus.add("Reunião terça 14h", domain="memory")
result = nexus.search("quando é a reunião?")
print(result.answer)

# Twice rule — lesson aprendida
nexus.lesson(
    title="Sempre validar embedding dim antes de inserir em pgvector",
    body="Dim 1536 ≠ 1024 → INSERT explode silenciosamente",
    severity="critical",
)

# Decision com rationale
nexus.decision(
    title="Adotar pgvector em vez de Weaviate",
    description="Reduz containers; busca híbrida fica dentro de Eloquent",
    category="architecture",
)

# Grafo de entidades
graph = nexus.entity("foxpulse").graph()
for edge in graph.edges:
    print(edge.from_entity_slug, "→", edge.kind, "→", edge.to_entity_slug)

# Async também (recomendado em apps async)
import asyncio
from mnemonexus import AsyncNexus

async def main():
    async with AsyncNexus(token="...") as nexus:
        await nexus.add("…")
        r = await nexus.search("…")
asyncio.run(main())
```

## API resumida

### Paridade mem0
| Método | Endpoint | O que faz |
|---|---|---|
| `add(content, **)` | `POST /ingest` | Adiciona memória |
| `search(query, **)` | `POST /query` | Recall híbrido (FTS + vetor) |
| `get(slug)` | `GET /pages/{slug}` | Lê página |
| `update(slug, content)` | `PUT /pages/{slug}` | Supersede |
| `delete(slug)` | `DELETE /pages/{slug}` | Hard delete |
| `history(slug)` | `GET /pages/{slug}` | Cadeia de versões |

### Diferencial mnemonexus
| Método | Endpoint | O que faz |
|---|---|---|
| `compile(slug)` | `POST /pages/{slug}/compile` | Recompila wiki page |
| `extract_facts(text)` | `POST /facts/extract` | Facts + entidades + relações |
| `lesson(title, body)` | `POST /lessons` | Lesson com twice-rule |
| `decision(title, description)` | `POST /decisions` | Decisão com rationale |
| `compact_session(id)` | `PUT /sessions/{id}` | Fecha + sumariza sessão |
| `entity(slug).graph()` | `GET /entities/{slug}/graph` | Grafo BFS da entidade |
| `search_entity(q)` | `GET /entities` | Busca grafo de entidades |

## Errors

`NexusError` é a base. Subclasses:
- `AuthError` — 401/403
- `NotFoundError` — 404
- `ValidationError` — 422

## Cookbook

Veja [`examples/`](./examples/):

1. `01_hello_world.py` — add + search
2. `02_with_karpathy.py` — wiki compilada
3. `03_with_lessons.py` — twice rule
4. `04_multi_tenant.py` — isolamento por agent_id/tenant
5. `05_rag_over_wiki.py` — RAG com histórico

## Dev

```bash
git clone https://github.com/lrdeoliveira/mnemonexus-python
cd mnemonexus-python
pip install -e ".[dev]"
pytest
```

## Licença

MIT.
