hermes-ai-know 0.3.0__tar.gz

hermes_ai_know-0.3.0/PKG-INFO

@@ -0,0 +1,103 @@
+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.

hermes_ai_know-0.3.0/README.md

@@ -0,0 +1,92 @@
+# 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.

hermes_ai_know-0.3.0/ai_know/__init__.py

@@ -0,0 +1,3 @@
+"""AI KNOW - Memory Kernel for long-running AI agents."""
+
+__version__ = "0.3.0"

hermes_ai_know-0.3.0/ai_know/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""Client-side adapters that let external agents talk to AI KNOW.
+
+Adapters live in the AI KNOW repo (not in each agent's codebase) so:
+    1.  We can unit-test the wire contract in-process with FastAPI's
+        TestClient — no cross-repo dev loop needed.
+    2.  Every agent gets the same auto-degrade + timeout semantics for
+        free; we don't reinvent them per integration.
+    3.  If the wire contract shifts, the adapter shifts with it in the
+        same PR — no drift.
+
+v0.1 ships one adapter: :class:`AIKnowHermesAdapter` (see ``hermes.py``),
+targeting upstream NousResearch/hermes-agent.
+"""
+
+from .hermes import (  # noqa: F401
+    AIKnowHermesAdapter,
+    HermesSessionState,
+    AdapterConfig,
+)
+
+__all__ = [
+    "AIKnowHermesAdapter",
+    "HermesSessionState",
+    "AdapterConfig",
+]