Metadata-Version: 2.5
Name: nafsai
Version: 0.1.2
Summary: The Arabic-First Memory Layer for Local AI
Project-URL: Homepage, https://github.com/NafsAI/NafsAI
Project-URL: Repository, https://github.com/NafsAI/NafsAI
Author: NafsAI
License: Apache-2.0
License-File: LICENSE
License-File: LICENSE.txt
Keywords: AI,LLM,arabic,local,memory,ذاكرة,ذكاء اصطناعي,عربي
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: Arabic
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=2.0.0
Requires-Dist: sentence-transformers>=3.0.1
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: sqlite-vec>=0.1.9; extra == 'full'
Description-Content-Type: text/markdown


```markdown
<div align="center">

<img src="assets/logo.png" alt="NafsAI" width="120"/>

# NafsAI
### The Arabic-First Memory Layer for Local AI
### طبقة الذاكرة العربية للذكاء الاصطناعي المحلي

[![PyPI](https://img.shields.io/pypi/v/nafsai)](https://pypi.org/project/nafsai)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Arabic-First](https://img.shields.io/badge/Arabic--First-✓-green.svg)]()

**Arabic · English · No Cloud · No API · Your Device Only**

*Built in Saudi Arabia 🇸🇦*

</div>

---

## The Problem

Every AI chatbot you build forgets everything after each conversation.

كل chatbot تبنيه ينسى كل شيء بعد كل محادثة.

## The Solution

```python
from nafsai import Agent

agent = Agent()
answer = agent.chat("What do you remember about me?", your_llm)
# Remembers. Always. In Arabic and English.
# يتذكر. دائماً. بالعربية والإنجليزية.
```

**Permanent memory. No cloud. Arabic-first. Works in English too.**

**ذاكرة دائمة. بدون سحابة. عربي أولاً. يعمل بالإنجليزية أيضاً.**

---

## Why NafsAI?

| | mem0 | Zep | Letta | **NafsAI** |
|--|------|-----|-------|------------|
| Arabic-First | ❌ | ❌ | ❌ | **✅** |
| No Cloud Required | ⚠️ | ⚠️ | ⚠️ | **✅** |
| pip install only | ❌ | ❌ | ❌ | **✅** |
| No Docker | ❌ | ❌ | ❌ | **✅** |
| Local & Private | ⚠️ | ⚠️ | ⚠️ | **✅** |
| Works Offline | ❌ | ❌ | ❌ | **✅** |

---

## Installation

```bash
pip install nafsai
```

That's it. No Docker. No server. No API key.

هذا كل شيء. بدون Docker. بدون خادم. بدون API key.

---

## Quick Start

```python
from nafsai import Agent

agent = Agent()

def my_llm(prompt: str) -> str:
    # your LLM here — Ollama, OpenAI, Gemini, anything
    return your_llm_function(prompt)

# First session
agent.chat("اسمي عبدالله وأنا مطور Python", my_llm)
agent.chat("My name is John and I work in Riyadh", my_llm)

# Close and reopen — memory persists
# أغلق وأعد التشغيل — الذاكرة تبقى

# New session
agent2 = Agent()
agent2.chat("هل تتذكرني؟", my_llm)
# → "نعم عبدالله، أنت مطور Python"

agent2.chat("Who am I?", my_llm)
# → "You are John, you work in Riyadh"
```

---

## How It Works

```
Your App
    ↓
Agent   ← combines all components
    ↓
Router  ← classifies question  (coding / reasoning / general)
Memory  ← permanent storage    (SQLite + FTS5 + vectors)
Cache   ← smart TTL cache
Session ← current conversation context
    ↓
Your LLM ← Ollama / OpenAI / Gemini / anything
```

### Three Memory Modes

NafsAI detects your environment and uses the best available mode:

| Mode | Engine | Performance |
|------|--------|-------------|
| `full` | FTS5 + sqlite-vec | Best |
| `fts_only` | FTS5 only | Good |
| `numpy_only` | numpy cosine | Always works |

No configuration needed. It just works.

---

## Components

| Component | Description | الوصف |
|-----------|-------------|-------|
| `Memory` | Permanent local memory | ذاكرة دائمة محلية |
| `Router` | Smart question routing | توجيه ذكي للأسئلة |
| `Normalizer` | Arabic text normalization | تطبيع النص العربي |
| `Cache` | TTL-based smart cache | كاش ذكي |
| `Session` | Conversation context | سياق المحادثة |
| `Agent` | All-in-one interface | واجهة موحدة |

---

## Works With Any LLM

```python
# Ollama (local)
import ollama

def llm(prompt: str) -> str:
    return ollama.chat(
        model="llama3.2",
        messages=[{"role": "user", "content": prompt}],
    )["message"]["content"]

# OpenAI
from openai import OpenAI

client = OpenAI()

def llm(prompt: str) -> str:
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    ).choices[0].message.content

# Any function that takes str and returns str
agent.chat("your question", llm)
```

---

## Tests & Quality

All tests pass across all memory modes:

| Test File | Coverage |
|-----------|----------|
| `test_agent.py` | Agent pipeline, cache hits, LLM errors, prompt building |
| `test_memory.py` | Save/search, user facts, normalization, persistence, all 3 modes |
| `test_cache.py` | TTL rules, route isolation, bad responses, Arabic normalization |
| `test_router.py` | Keyword rules, semantic routing, Arabic & English questions |
| `test_normalizer.py` | Hamza, Tashkeel, numbers, math symbols, mixed text |
| `test_session.py` | Turn limits, context window, f-string format, truncation |

```bash
pip install -e ".[dev]"
pytest
# ✓ All tests passed

---

## Privacy

```
✓ Everything stored locally — your device only
✓ No data leaves your machine
✓ No telemetry
✓ No internet required after installation
✓ GDPR-friendly by design
```

```
✓ كل شيء يُخزن محلياً على جهازك فقط
✓ لا بيانات تغادر جهازك
✓ لا تتبع
✓ لا إنترنت مطلوب بعد التثبيت
```

---

## Roadmap

- [x] SQLite + FTS5 + vector search
- [x] Arabic-English bilingual support
- [x] Smart fallback system

next version: 
- [ ] MCP server support

---

## Contributing

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

All contributions welcome — Arabic and English.

كل المساهمات مرحب بها — بالعربية والإنجليزية.

---

<div align="center">

**Built in Saudi Arabia 🇸🇦 — For the Arabic AI Ecosystem**

[PyPI](https://pypi.org/project/nafsai) ·
[Documentation](https://github.com/NafsAI/NafsAI/wiki) ·
[Issues](https://github.com/NafsAI/NafsAI/issues) ·
[Discussions](https://github.com/NafsAI/NafsAI/discussions)

*"The Arabic world deserves its own AI tools — built here, for here, by us."*

*"العالم العربي يستحق أدوات AI مبنية هنا، لنا، منّا."*

</div>
```
