openaugi 0.1.0__tar.gz

openaugi-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+**What happened?**
+
+**What did you expect?**
+
+**Steps to reproduce:**
+
+1.
+2.
+3.
+
+**Environment:**
+- OS:
+- Python version:
+- OpenAugi version:

openaugi-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest a feature
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**Proposed solution:**
+
+**Alternatives considered:**

openaugi-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What does this PR do? 1-3 bullet points. -->
+
+## Test plan
+
+<!-- How did you verify this works? -->
+
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] Lint clean (`ruff check src tests`)

openaugi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: .venv/bin/ruff check src tests
+
+      - name: Type check with pyright
+        run: .venv/bin/pyright src
+
+      - name: Run tests
+        run: .venv/bin/pytest tests/ -v --tb=short

openaugi-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e ".[dev]"
+      - name: Lint
+        run: .venv/bin/ruff check src tests
+      - name: Type check
+        run: .venv/bin/pyright src
+      - name: Tests
+        run: .venv/bin/pytest tests/ -v --tb=short
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: python3 -m pip install build
+      - name: Build wheel and sdist
+        run: python3 -m build
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/openaugi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openaugi-0.1.0/.gitignore

@@ -0,0 +1,191 @@
+*local*
+env
+.venv
+*.pyc
+*.npy
+*data/
+.vscode/
+.DS_Store
+*.env
+storage/
+*.log
+*lib/
+*.json
+notes_network.html
+*.duckdb*
+*.duckdb
+*.db
+*.db-wal
+*.db-shm
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc

openaugi-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
+    hooks:
+      - id: pyright
+        files: ^src/
+        additional_dependencies:
+          - "pydantic>=2.6"
+          - "typer>=0.12"
+          - "rich>=13"
+          - "mcp>=1.0"
+          - "numpy>=1.26"
+          - "openai>=1.0"
+          - "tiktoken>=0.7"

openaugi-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+---
+name: architecture
+description: System architecture for OpenAugi — blocks+links data model, processing layers, module map
+---
+
+# OpenAugi Architecture
+
+A self-hostable personal intelligence engine. One `pip install`. One SQLite file. One MCP server.
+
+## Data Model
+
+Two tables. That's the whole store.
+
+```
+blocks (id, kind, content, summary, embedding, source, title, tags, timestamp, metadata, content_hash)
+links  (from_id, to_id, kind, weight, metadata)  — PK: (from_id, to_id, kind)
+```
+
+**Block kinds:** document, entry, tag, cluster (M2), summary (M2)
+**Link kinds:** split_from, tagged, links_to, member_of (M2), summarizes (M2)
+
+Everything is a block. Structure lives in the links, not in the schema.
+
+## Processing Layers
+
+| Layer | Cost | What | Requires |
+|-------|------|------|----------|
+| **Layer 0** | FREE | Split, tag/link extract, FTS, dedup hash | Python + SQLite |
+| **Layer 1** | ~$0 | Embed (local default), hub scoring (SQL) | sentence-transformers (local) |
+| **Layer 2** | $$$ | Entity extraction, summaries, clustering | LLM (deferred to M2) |
+
+## Module Map
+
+```
+src/openaugi/
+├── model/
+│   ├── block.py          # Block Pydantic model
+│   ├── link.py           # Link Pydantic model
+│   └── protocols.py      # EmbeddingModel, LLMModel protocols
+├── adapters/
+│   └── vault.py          # Obsidian vault → blocks + links
+├── pipeline/
+│   ├── runner.py          # Layer 0 orchestrator (incremental ingestion)
+│   ├── embed.py           # Layer 1 embedding step → vec_blocks (sqlite-vec)
+│   ├── rerank.py          # Dedup + MMR re-ranking for get_context
+│   └── watcher.py         # File watcher — debounced incremental ingest on vault changes
+├── store/
+│   └── sqlite.py          # SQLite backend (WAL, FTS5, sqlite-vec vec0, CASCADE)
+├── models/
+│   ├── __init__.py        # Factory: get_embedding_model(), get_llm_model()
+│   └── embeddings/
+│       ├── sentence_transformer.py  # Local default (free)
+│       └── openai.py               # OpenAI API adapter
+├── mcp/
+│   ├── server.py          # MCP tools (read + write + streams), stdio + streamable-http transport
+│   ├── doc_writer.py      # VaultWriter — writes .md to OpenAugi/ in vault
+│   └── stream_manager.py  # StreamManager — workstream CRUD (OpenAugi/Streams/)
+├── cli/
+│   └── main.py            # typer CLI (up, ingest, serve, watch, search, hubs, status, service)
+└── config.py              # TOML config loader + .env loader
+```
+
+## Key Flows
+
+### Ingest (Layer 0 + 1)
+
+```
+Vault .md files
+  → parse_vault_incremental()  [adapters/vault.py]
+    → file hash check (skip unchanged)
+    → split by H3 dates → entry blocks
+    → extract tags → tag blocks + tagged links
+    → extract [[wikilinks]] → links_to links
+    → document block + split_from links
+  → insert blocks + links  [store/sqlite.py]
+  → FTS5 auto-indexed via triggers
+  → run_embed()  [pipeline/embed.py]
+    → embed blocks where embedding IS NULL
+    → write float32 blobs to blocks.embedding + vec_blocks (sqlite-vec)
+```
+
+### Query (MCP)
+
+```
+Claude → MCP tool call → server.py
+  → search: sqlite-vec KNN (semantic) or FTS5 (keyword) + filters
+  → get_block / get_blocks: full content by ID (single or batch)
+  → get_related: follow links from/to a block
+  → traverse: multi-hop graph walk
+  → get_context: FTS + semantic (3× overfetch)
+                 → deduplicate (cosine grouping, rerank.py)
+                 → MMR re-rank
+                 → expand via links
+  → recent: recently created blocks
+  → write_document / write_thread / write_snip: save notes to vault
+  → list_streams / get_stream_context / make_stream / update_stream: workstream CRUD
+```
+
+### Hub Scoring
+
+Pure SQL aggregation at query time (no stored table):
+```
+hub_score = w_in * ln(1 + inbound_links) + w_out * ln(1 + outbound_links) + w_ent * ln(1 + entry_count)
+```
+
+## Design Decisions
+
+See [docs/plans/m0.md](docs/plans/m0.md) § Key Design Decisions for full rationale.
+
+- **SQLite over DuckDB**: WAL mode concurrent writes. DuckDB is single-writer.
+- **sqlite-vec over FAISS**: KNN via `vec0` virtual table — everything in one file, no separate index management. Embeddings normalized on write so L2 distance ≡ cosine.
+- **Content hash as block identity**: `hash(source_path + content_hash)` — stable across section reordering.
+- **Tags as blocks**: First-class graph nodes. Hub scoring, traversal, entity resolution work uniformly.
+- **Default local embeddings**: sentence-transformers, no API key. Users upgrade via config.
+- **`get_context` dedup + MMR**: Over-fetches 3× candidates, collapses near-duplicates via cosine grouping, re-ranks for diversity before returning. See [docs/MCP_SERVER.md](docs/MCP_SERVER.md) for tuning.
+
+## Running
+
+### Quick start (one command)
+
+```bash
+openaugi init          # one-time: configure embedding model, API key, vault path
+openaugi up            # daily: sync vault + file watcher + MCP server
+```
+
+`openaugi up` is the single command to run OpenAugi:
+
+1. **Incremental ingest** — syncs vault to SQLite (skips unchanged files via content hash)
+2. **File watcher** — daemon thread watches for `.md` changes, debounces (default 30s), re-ingests
+3. **MCP server** — foreground, stdio or HTTP transport
+
+Embedding is attempted with the user's configured model. If it fails, blocks are saved without embeddings and retried on the next watcher cycle. SQLite WAL mode handles concurrent reads (MCP) and writes (watcher) without locking.
+
+### Individual commands
+
+| Command | What |
+|---------|------|
+| `openaugi serve` | MCP server only (stdio or HTTP) |
+| `openaugi watch` | File watcher only (incremental ingest on vault changes) |
+| `openaugi up` | Both in one process |
+
+### Transports
+
+Two transport modes — see [docs/REMOTE_ACCESS.md](docs/REMOTE_ACCESS.md) for full setup.
+
+| Transport | Command | Use Case |
+|-----------|---------|----------|
+| stdio (default) | `openaugi up` | Claude Desktop/Code on same machine |
+| streamable-http | `openaugi up --transport http` | Remote clients, Claude mobile via Cloudflare Tunnel |
+
+Service management (macOS): `openaugi service install/uninstall/status` — launchd plist, starts on boot.
+
+## Plans
+
+- [docs/plans/overall-mvp.md](docs/plans/overall-mvp.md) — Milestones M0–M5
+- [docs/plans/future-work.md](docs/plans/future-work.md) — Deferred features

openaugi-0.1.0/CLAUDE.md

@@ -0,0 +1,51 @@
+You build software as a senior staff engineer who wants a code base that is modular, extensible, simple, well tested, and reliable.
+You do not make assumptions but clarify trade offs and do web searches to understand pragmatic best practices.
+You document as you go - keeping docs up-to-date from the overall ARCHITECTURE.md linking to other docs when needed to describe features and why.
+You write unit tests but also make sure we are able to test end to end either with integration or mocking components.
+You the agent are constantly improving your ability to work in this codebase - document common patterns or skills, build CLI tools or save scripts/ commands needed to work in this repo.
+
+# Quick reference
+
+```bash
+# Install (dev)
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+
+# Run full CI check (lint + types + tests) — ALWAYS run before pushing
+./scripts/check.sh
+
+# Run tests only
+.venv/bin/python -m pytest tests/ -v
+
+# Ingest fixture vault
+.venv/bin/openaugi ingest --path tests/fixtures/vault --db /tmp/test.db
+
+# CLI commands
+.venv/bin/openaugi status --db /tmp/test.db
+.venv/bin/openaugi hubs --db /tmp/test.db
+.venv/bin/openaugi search "query" --db /tmp/test.db --keyword
+
+# Lint
+.venv/bin/ruff check src tests
+```
+
+# Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system map.
+
+**Core data model:** Two tables — `blocks` and `links`. Everything is a block (documents, entries, tags). Structure lives in the links.
+
+**Key modules:**
+- `src/openaugi/model/` — Block, Link (Pydantic), protocols (EmbeddingModel, LLMModel)
+- `src/openaugi/adapters/vault.py` — Obsidian vault → blocks + links
+- `src/openaugi/store/sqlite.py` — SQLite backend (WAL, FTS5, sqlite-vec vec0, CASCADE)
+- `src/openaugi/pipeline/runner.py` — Layer 0 orchestrator
+- `src/openaugi/pipeline/embed.py` — Layer 1 embedding step
+- `src/openaugi/mcp/server.py` — 5 MCP tools for Claude
+- `src/openaugi/cli/main.py` — typer CLI (ingest, serve, search, hubs, status)
+
+# Document as you go
+Plans go in docs/plans folder. Move them to docs/archive when done.
+
+ARCHITECTURE.md is the overall entry point map into the codebase - keep this up-to-date and walk the other docs.
+
+Docs should follow Claude skill format - name: and description: at the top that we can scan the top only to find relevant docs.

openaugi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to OpenAugi
+
+Thanks for your interest in contributing.
+
+## Setup
+
+```bash
+git clone https://github.com/openaugi/openaugi.git
+cd openaugi
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+# Run tests
+.venv/bin/python -m pytest tests/ -v
+
+# Lint
+.venv/bin/ruff check src tests
+
+# Type check
+.venv/bin/pyright src
+```
+
+## Pull Requests
+
+- One focused change per PR
+- Include tests for new functionality
+- Run `pytest` and `ruff check` before submitting
+- Keep PRs small — easier to review, faster to merge
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for how the system is structured.
+
+## Code Style
+
+- Python 3.12+
+- Ruff for linting and formatting
+- Pyright for type checking
+- Pydantic for data models
+- Keep it simple — no premature abstraction

openaugi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chris Lettieri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.