Metadata-Version: 2.4
Name: aidos
Version: 0.0.1
Summary: aidos (AI Diary Operating System) — the control-plane CLI for an agentic harness: roadmap index, knowledge-graph reindex, and module setup.
Author: Yingding Wang
License-Expression: MIT
Keywords: aidos,ai-diary,harness,control-plane,knowledge-graph,roadmap
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.15.1
Provides-Extra: mcp
Requires-Dist: mcp>=1.27.1; extra == "mcp"
Dynamic: license-file

# aidos

**AI diary OS** — the control-plane CLI for an agentic harness. Index your roadmaps, keep knowledge graphs fresh, and stand up new modules, all from one command.

## What it does

`aidos` is the operations layer that sits *above* a multi-module workspace and manages the shared machinery your agent depends on:

- **Roadmap index** — parse a roadmap markdown into identified items (stable UUIDs), classify them done / active / deferred, and build a SQLite **FTS5** keyword index for fast search. The markdown stays the source of truth; the index is derived.
- **Graph reindex** — discover every subproject's knowledge graphs, report freshness, and rebuild them in the correct virtualenv. It never kills your MCP servers — it reports which ones need a restart.
- **Module setup** — a reproducible recipe (and script) to make a new Python module a first-class citizen: its own venv, its own code + docs graphs, and wiring into the shared portal.

It is **CLI-first**: all logic lives behind plain functions, so it is testable and scriptable without a server. A future control **MCP** wraps the same CLI.

The name is a nod to [`aidiary`](https://pypi.org/project/aidiary/) (the *AI diary* memory system): `aidos` is the **OS** layer around it.

## Install

Requires: Python 3.12+

```bash
pip install aidos
```

Building a module's own knowledge graphs additionally uses `aidiary[graphs]` (installed editable in dev):

```bash
pip install "aidiary[graphs]"
```

## Quick start

### 1. Check graph freshness across the workspace

```bash
aidos status
```

Lists each subproject's graph layers (code / docs / …) with a ✓ fresh / ⚠ stale / ✗ missing badge based on `graph.json` mtime vs. newest source.

### 2. Index a roadmap and search it

```bash
aidos roadmap index path/to/ProjectRoadmap.md
aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db
```

`index` assigns a stable UUID to every item and writes a SQLite FTS5 index + a JSON sidecar. `search` is instant keyword retrieval — no embeddings, no LLM.

### 3. Preview a done / active split (non-destructive)

```bash
aidos roadmap split path/to/ProjectRoadmap.md
```

Writes `*-archive.md` (done) and `*-active.md` (active + deferred) previews. **The original file is never modified** — you review first.

### 4. Rebuild knowledge graphs

```bash
aidos reindex --dry-run          # show what would rebuild
aidos reindex --subproject aidos # rebuild one subproject's code graph
```

Any rebuilt layer is reported as `restart_required` — restart those MCP servers through your editor (or your restart script), never by killing the process.

## Directory layout

```
my-module/
├── pyproject.toml
├── config/graphs.toml        # graphs.code (src/, ast) + graphs.docs (docs/, semantic)
├── src/<pkg>/                # your package
├── docs/                     # concept docs (feed the docs graph)
└── output/                   # generated artifacts
    ├── aidos/                # roadmap index db + json sidecar
    └── graphs/{code,docs}/   # graph.json + graph.html
```

## Command reference

| Command | Purpose |
|---------|---------|
| `aidos status` | Report knowledge-graph freshness across subprojects |
| `aidos roadmap index <file>` | Build the SQLite FTS5 search index for a roadmap |
| `aidos roadmap search <query> --db <db>` | Keyword-search the index |
| `aidos roadmap split <file>` | Non-destructive done / active split preview |
| `aidos reindex [--subproject N] [--docs] [--dry-run]` | Rebuild per-subproject graphs |

## Design principles

- **Markdown / files stay the source of truth** — every index, db, and graph is a *derived* artifact. Producers and consumers connect via files on disk, not imports.
- **Keyword over embeddings** — on a few-hundred-item corpus, SQLite FTS5 is instant and sufficient; vector search is deferred until the data demands it.
- **Never kill a stdio MCP server** — reindex reports `restart_required`; it does not respawn processes.

## What's new

### 0.0.1

**First cut — the Developer-Control plane CLI**

- **`roadmap`** — `index` (parse → stable UUIDs → done/active/deferred → SQLite FTS5 + JSON sidecar), `search` (FTS5 keyword), `split` (non-destructive done/active preview).
- **`reindex`** — discover subproject graphs, report freshness, rebuild via each subproject's `aidiary-graphs`; reports `restart_required` (never kills MCP servers).
- **`status`** — workspace-wide graph freshness.
- **Reproducible module setup** — idempotent `setup.sh` (venv + editable installs + graphs) and a documented "make a module a first-class harness citizen" guide.
- **Typer CLI**, stdlib-only core (plus Typer); builds to sdist + wheel.
