Metadata-Version: 2.4
Name: nyron-ai
Version: 0.1.1
Summary: Graph-based AI memory system with Neo4j, recall scoring, and conflict analysis
Author-email: Danilka <nishandanilka@gmail.com>, Randiya <randiya0123@gmail.com>
Maintainer-email: Danilka <nishandanilka@gmail.com>, Randiya <randiya0123@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Danilka-Akarawita/Neur0
Project-URL: Bug Tracker, https://github.com/Danilka-Akarawita/Neur0/issues
Keywords: ai,memory,neo4j,graph,openai,long-term memory,personalization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: neo4j>=5.20.0
Requires-Dist: openai>=1.30.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: motor
Requires-Dist: fastapi
Requires-Dist: uvicorn

# Neur0 (nyron-ai)

Neur0 is a graph-based AI memory system designed for long-term personalization. It uses **Neo4j** to build isolated user subgraphs, resolves memory conflicts using semantic analysis, ranks retrieved memories using recall scoring, and keeps short-term context utilizing **MongoDB**.

---

## Features

- **Graph-Based Memory**: Build highly structured, isolated memory subgraphs for individual users.
- **Semantic Conflict Resolution**: Automatically detect when new facts contradict existing memories and mark old facts as conflicted.
-**Recall Scoring**: Rank memories dynamically based on a combination of semantic similarity, recency, and reinforcement (access frequency).
-**Short-Term Context**: Manage short-term context and resolve pronouns/references using MongoDB.
-**OpenAI Integration**: Cleanly extract facts and embeddings using OpenAI models.
-**Built-in API Server**: Instantly run a FastAPI server using the CLI to add, search, and manage memories via HTTP requests.

---

## Prerequisites

- **Python**: `>=3.9`
- **Neo4j Database**: A running instance (e.g. Neo4j Desktop, AuraDB, or Docker).
- **MongoDB** *(Optional)*: Required if you want to enable the short-term memory store.
- **OpenAI API Key**: Required for fact extraction, query resolution, and embeddings.

---

## Installation

You can install Neur0 from PyPI:

```bash
pip install nyron-ai
```

For local development and testing, clone the repository and run:

```bash
pip install -e .
```

---

## Quickstart

### 1. Configure Environment Variables
Create a `.env` file in your project root with your database credentials and API keys:

```env
OPENAI_API_KEY=your-openai-key
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

# Optional: MongoDB for short-term memory
MONGO_URI=mongodb://localhost:27017
MONGO_DB=neur0
```

### 2. Python Code Usage
Here is how to initialize the memory client, save a memory, and query it:

```python
import asyncio
from neuro import (
    MemoryClient,
    Neo4jGraphStore,
    MongoStore,
    OpenAIProvider,
    OpenAIEmbeddingProvider,
)

async def main():
    # 1. Initialize Stores
    graph_store = Neo4jGraphStore(
        uri="bolt://localhost:7687",
        username="neo4j",
        password="password",
    )
    graph_store.initialize()

    # Optional MongoDB short-term store
    mongo_store = MongoStore(uri="mongodb://localhost:27017", db_name="neur0")
    await mongo_store.initialize()

    # 2. Setup AI Providers
    llm = OpenAIProvider(api_key="your-api-key", model="gpt-4o-mini")
    embedder = OpenAIEmbeddingProvider(api_key="your-api-key", model="text-embedding-3-small")

    # 3. Create Memory Client
    memory = MemoryClient(
        graph_store=graph_store,
        llm=llm,
        embedder=embedder,
        short_term_store=mongo_store,
    )

    # 4. Save a Memory
    user_id = "user_128r"
    result = await memory.add(
        user_id=user_id,
        message="I studied computer science at Cambridge University.",
    )
    print("Saved facts:", result["saved_count"])

    # 5. Search memories
    search_results = await memory.search(
        user_id=user_id,
        query="Where did I go to college?",
    )
    for res in search_results:
        fact = res["fact"]
        print(f"Fact: {fact.subject} {fact.predicate} {fact.object}")
        print(f"Recall Score: {res['recall_score']}")

    # Clean up connections
    graph_store.close()
    mongo_store.close()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Running the API Server

Neur0 includes a built-in command line utility to start a FastAPI backend. 

Simply run:
```bash
neuro-api
```

The API will start running at `http://localhost:8000`. 

### Available Endpoints

- **`POST /add_memory`**: Add a new user message, extract facts, and handle conflicts.
  ```json
  {
    "user_id": "user_128r",
    "message": "I study computer science at Cambridge."
  }
  ```
- **`POST /search_memory`**: Search and retrieve relevant memories.
  ```json
  {
    "user_id": "user_128r",
    "query": "Where do I study?",
    "limit": 5
  }
  ```
- **`DELETE /delete_subgraph/{user_id}`**: Delete all graph nodes and memories for a specific user.

---

## License
MIT License.
