nafsai 0.1.2

<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?

Installation

pip install nafsai

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

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

Quick Start

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:

No configuration needed. It just works.

Components

Works With Any LLM

# 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:

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.

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