Metadata-Version: 2.4
Name: hermes-ai-know
Version: 0.3.0
Summary: AI KNOW - Memory Kernel for long-running AI agents (Hermes ecosystem)
Author: ASMAS
License: MIT
Project-URL: Source, https://github.com/asmas-ai/ai-know
Project-URL: Blueprint, https://github.com/asmas-ai/ai-know/blob/main/docs/ENGINEERING_UPGRADE_BLUEPRINT.md
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# AI KNOW - Python MVP

Python 3.11 + FastAPI implementation of the AI KNOW Memory Kernel v0.1.
This is the **primary execution path** for v0.1; the Rust code under
`src/backend/memory-core/` is retained as a reference implementation.

## Layout

```
python-mvp/
├── ai_know/
│   ├── main.py          # FastAPI app factory
│   ├── config.py        # Pydantic Settings (env-driven)
│   ├── api/             # HTTP routers (health, events, memories, ...)
│   ├── core/            # Ingestor, extractor, arbitrator, ...   (PR 3+)
│   ├── db/              # SQLAlchemy models + repositories       (PR 2)
│   ├── schemas/         # Pydantic request/response schemas       (PR 3+)
│   ├── providers/       # Embedding + LLM providers               (PR 4+)
│   └── jobs/            # Background jobs (dream, consolidation)  (PR 7+)
├── migrations/          # Alembic                                  (PR 2)
├── tests/
│   ├── unit/            # No I/O
│   ├── integration/     # Needs Postgres / Redis                    (PR 2+)
│   └── evals/           # Mini evals                                 (PR 8)
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── README.md
```

## Quick start

From the ai-know repo root:

```bash
docker compose up --build
# One-shot: apply the schema.
docker compose exec api alembic upgrade head
curl http://localhost:8090/health
# → {"status":"ok","version":"0.1.0","environment":"dev"}
curl http://localhost:8090/health/ready
# → {"status":"ok",...,"database":"ok","redis":"ok"}
```

Host ports: **API 8090, Postgres 5433, Redis 6380** (they coexist with
Hermes on 8080/5432 and Claudio on 3001).

## Local dev (no Docker)

```bash
cd src/backend/python-mvp
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL=postgresql+psycopg://ai_know:ai_know_dev@localhost:5433/ai_know
export REDIS_URL=redis://localhost:6380/0
alembic upgrade head
uvicorn ai_know.main:app --reload --port 8080
```

## Tests

Unit only (no I/O):
```bash
pytest tests/unit -v
```

Integration (needs docker compose up):
```bash
# From inside the running api container:
docker compose exec api python -m pytest tests/integration -v
```

## PR status (as of v0.1.0 tag)

| PR | Scope                            | Status | Tests   |
| -- | -------------------------------- | ------ | ------- |
| 1  | scaffold / FastAPI / health      | ✅ done | –       |
| 2  | DB migrations (9 tables + repos) | ✅ done | 14/14   |
| 3  | Events API                        | ✅ done | 44/44   |
| 4  | Episode + Claim extraction        | ✅ done | 82/82   |
| 5  | Arbitration + consolidation       | ✅ done | 109/109 |
| 6  | Context Pack builder              | ✅ done | 149/149 |
| 7  | Feedback engine                   | ✅ done | 174/174 |
| 8  | Mini evals                        | ✅ done | 178/178 |
| 9  | Hermes adapter (dogfooding)       | ✅ done | 187/187 |
| 10 | v0.1 release polish               | ✅ done | 187/187 |

**v0.1 backend RELEASE-READY.** See the top-level [CHANGELOG.md](../../../CHANGELOG.md)
for landing dates and commits.  See [`ai_know/adapters/hermes.py`](./ai_know/adapters/hermes.py)
for the client-side SDK that lets hermes-agent (and any other host) talk
to this backend without reimplementing the wire contract.
