Metadata-Version: 2.4
Name: bio-agent-os
Version: 0.1.0
Summary: Open-source Bio-Inspired Memory Framework for AI Agents — Biết nhớ, Biết quên, Biết tư duy.
Author-email: Locaith Solution Tech <contact@locaith.com>
License: MIT
Project-URL: Homepage, https://github.com/locaith/bio-agent-os
Project-URL: Documentation, https://github.com/locaith/bio-agent-os#readme
Project-URL: Repository, https://github.com/locaith/bio-agent-os
Project-URL: Issues, https://github.com/locaith/bio-agent-os/issues
Keywords: ai,memory,bio-inspired,agent,llm,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == "gemini"
Provides-Extra: ollama
Requires-Dist: aiohttp>=3.9.0; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: google-genai>=1.0.0; extra == "all"
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

<p align="center">
  <h1 align="center">🧠 Bio-Agent OS</h1>
  <p align="center"><strong>Open-source Bio-Inspired Memory Framework for AI Agents</strong></p>
  <p align="center"><em>Biết nhớ · Biết quên · Biết tư duy</em></p>
  <p align="center">Designed by <a href="https://locaith.com">Locaith Solution Tech</a> | 🇻🇳 Make in Vietnam</p>
</p>

---

## 🔬 Vấn đề

Mọi AI hiện tại (ChatGPT, Claude, Gemini) đều bị giới hạn bởi **Context Window** — một vùng nhớ tạm thời bị xoá sạch sau mỗi phiên hội thoại. Giải pháp "Compact" của Big Tech chỉ là **nén rác thành rác nhỏ hơn**.

**Bio-Agent OS** giải quyết vấn đề này bằng cách mô phỏng cơ chế trí nhớ sinh học của con người:

| Cơ chế | Não người | Bio-Agent OS |
|--------|-----------|--------------|
| **Hippocampus** | Dán nhãn, phân loại ký ức | `Hippocampus` — Label metadata real-time |
| **Synaptic Pruning** | Cắt tỉa khớp thần kinh rác | `GarbageCollector` — TTL + Ebbinghaus decay |
| **Encoding Shift** | Nén sự kiện → Logic trừu tượng | `Hippocampus.consolidate()` — Core Identity |
| **Prefrontal Cortex** | Bộ đệm ngắn hạn | `L1WorkingMemory` — Episodic buffer |
| **Neocortex** | Bộ nhớ dài hạn | `L2SemanticMemory` — Vector + Time-decay |
| **Association Areas** | Kết nối thông tin | `KnowledgeGraph` — Entity-Relationship |

## 🏗️ Kiến trúc

```
bio_agent_os/
├── core/
│   ├── llm_engine.py        # LLM Abstraction (Gemini, Ollama, vLLM, OpenAI)
│   ├── router.py             # Intent classification (L1? L2? Graph?)
│   └── persona.py            # Core Identity — "Linh hồn" bất biến của AI
├── memory/
│   ├── l1_working.py         # Short-term buffer (TTL, CRUD)
│   ├── l2_semantic.py        # Long-term Vector Search + Ebbinghaus decay
│   └── knowledge_graph.py    # Entity-Relationship Graph (Reasoning DB)
├── background_jobs/
│   ├── hippocampus.py        # Sleep → Label + Encode (Sự kiện → Logic)
│   ├── graph_builder.py      # Extract Entities/Relations from text
│   └── garbage_collector.py  # TTL cleanup + Vector pruning
└── api/
    └── main.py               # FastAPI endpoints
```

## 🔄 Luồng vận hành

```
┌─────────────────────────────────────────────────────────┐
│  USER sends message                                      │
│  ↓                                                       │
│  Router.classify() → Needs L1? L2? Graph?               │
│  ↓                                                       │
│  Build Context: L1 (recent) + L2 (semantic) + Persona   │
│  ↓                                                       │
│  LLMEngine.generate() → Response to User                │
│  ↓                                                       │
│  Hippocampus.label() → Store in L1                      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  SLEEP CYCLE (Background / Idle)                         │
│  ↓                                                       │
│  GarbageCollector.run() → Prune junk from L1 + L2       │
│  ↓                                                       │
│  Hippocampus.consolidate() → Encode survivors → Persona │
│  ↓                                                       │
│  GraphBuilder.process() → Update Knowledge Graph        │
└─────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### Installation

```bash
# From PyPI (coming soon)
pip install bio-agent-os[gemini]

# From source
git clone https://github.com/locaith/bio-agent-os.git
cd bio-agent-os
pip install -e ".[gemini]"
```

### Setup

```bash
# Create .env file
echo "GEMINI_API_KEY=your-key-here" > .env
```

### Run the API Server

```bash
python -m bio_agent_os.api.main
# → http://localhost:8055
```

### Use as a Library

```python
import asyncio
from bio_agent_os import LLMEngine, L1WorkingMemory, Persona, Hippocampus, GarbageCollector

async def main():
    # 1. Initialize components
    engine = LLMEngine(backend="gemini", model_id="gemini-3-flash-preview")
    l1 = L1WorkingMemory(agent_name="my-agent")
    persona = Persona(name="my-agent")
    hippo = Hippocampus(engine=engine, l1=l1, persona=persona)
    gc = GarbageCollector(l1=l1)

    # 2. Ingest data (real-time labeling)
    await hippo.label_and_store("API /login trả về 500 do thiếu await", source="dev-log")
    await hippo.label_and_store("Hôm nay ăn phở, nước dùng hơi mặn", source="chat")

    # 3. Sleep cycle (prune + encode)
    gc.run()
    stats = await hippo.consolidate()
    
    # 4. Check Core Identity
    print(persona.get_identity_prompt())
    # → "Quy tắc: Khi gọi database trong async context, luôn sử dụng await."

asyncio.run(main())
```

### Use with Ollama (Local LLM)

```python
engine = LLMEngine(
    backend="ollama",
    model_id="llama3.1:8b",
    base_url="http://localhost:11434",
)
```

### Use with vLLM / LM Studio (OpenAI-compatible)

```python
engine = LLMEngine(
    backend="openai",
    model_id="Qwen/Qwen2.5-7B-Instruct",
    base_url="http://localhost:8000/v1",
)
```

## 📊 API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/chat` | Chat với AI (Router → L1+L2 → LLM → Response) |
| `POST` | `/api/ingest` | Nạp dữ liệu thô vào Pipeline (Chunk → Label → Store) |
| `POST` | `/api/sleep` | Kích hoạt vòng lặp đêm (Prune + Encode) |
| `GET` | `/api/state` | Xem trạng thái bộ nhớ (L1, L2, Graph, Persona) |
| `GET` | `/api/graph` | Xem Knowledge Graph data |
| `POST` | `/api/reset` | Hard reset L1 memory |

## 🧪 So sánh 3 chiều

| Tiêu chí | Compact (Big Tech) | Bio-Memory (Bio-Agent OS) |
|----------|-------------------|--------------------------|
| **Xử lý nhiễu** | Nén rác → rác nhỏ hơn | Tiêu hủy hoàn toàn (`rm -rf`) |
| **Cơ chế** | Cắt tỉa văn bản đồng bộ | Chuyển hóa bất đồng bộ (Sleep mode) |
| **Chi phí** | Đốt GPU liên tục | Tối ưu VRAM, chạy khi rảnh |
| **Kết quả** | Mất trí nhớ sau session | Tích luỹ Core Identity vĩnh viễn |
| **Scalability** | Tràn bộ nhớ → Hallucination | Chạy vĩnh viễn, không suy giảm |

## 🛡️ License

MIT License — Free for commercial and personal use.

## 🤝 Contributing

Pull requests welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

<p align="center">
  <strong>Bio-Agent OS</strong> — Trí nhớ sinh học cho AI thế hệ mới<br>
  <em>Designed with 🧠 by Locaith Solution Tech</em>
</p>
