aikb 0.0.2__tar.gz

aikb-0.0.2/.claude/CLAUDE.md

@@ -0,0 +1,30 @@
+# aikb — Project Instructions
+
+## What this is
+
+`aikb` provides programmatic CRUD for AI project knowledge bases (Claude Projects, Gemini Gems) via a `MutableMapping` interface compatible with `dol`.
+
+## Architecture
+
+Three-layer design in `aikb/base.py`:
+- **Provider protocol** (`KnowledgeBaseProvider`) — structural typing, no inheritance
+- **Store facade** (`KnowledgeFiles`) — `collections.abc.MutableMapping`
+- **Factory functions** (`LocalFiles`, `ClaudeProject`) — progressive disclosure
+
+Optional `aikb/mcp_server.py` exposes CRUD as MCP tools.
+
+## Skills
+
+Load the relevant skill when working in these areas:
+
+- **Maintaining/extending aikb code**: Read `.claude/skills/aikb-maintain/SKILL.md`
+- **Helping users install/configure aikb**: Read `.claude/skills/aikb-setup/SKILL.md`
+- **Syncing files between platforms**: Read `.claude/skills/aikb-sync/SKILL.md`
+
+## Key conventions
+
+- Provider methods raise `KeyError` on missing files
+- `list_files` / `__iter__` yield (generators, not lists)
+- Optional deps (`claudesync`, `fastmcp`) are lazy-imported via `_check_dependency()`
+- All arguments after the first positional are keyword-only
+- Zero core dependencies — extras for `claude`, `mcp`, `dol`

aikb-0.0.2/.claude/skills/aikb-maintain/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: aikb-maintain
+description: "Use when maintaining, extending, or debugging the aikb codebase. Covers adding new providers, modifying the store facade, updating tests, and architectural decisions."
+---
+
+# aikb: Codebase Maintenance
+
+Use this skill when modifying or extending the aikb package itself.
+
+## Architecture
+
+aikb has three layers:
+
+1. **Provider protocol** (`KnowledgeBaseProvider`) — structural typing via `Protocol`
+2. **Store facade** (`KnowledgeFiles`) — `MutableMapping` wrapping any provider
+3. **Factory functions** (`LocalFiles`, `ClaudeProject`) — progressive disclosure entry points
+
+All core code lives in `aikb/base.py`. The MCP server is in `aikb/mcp_server.py`.
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `aikb/base.py` | Protocol, KnowledgeFiles, all providers, KnowledgeMall, factories |
+| `aikb/__init__.py` | Public API exports only |
+| `aikb/mcp_server.py` | FastMCP server (gated behind `aikb[mcp]`) |
+| `tests/test_aikb.py` | pytest suite |
+| `pyproject.toml` | Build config, optional deps groups |
+
+## Adding a new provider
+
+1. Create a class in `aikb/base.py` implementing the four protocol methods:
+
+```python
+class NewPlatformProvider:
+    def __init__(self, ...):
+        ...
+
+    def list_files(self, project_id: str) -> Iterator[str]:
+        ...  # yield filenames
+
+    def read_file(self, project_id: str, filename: str) -> str:
+        ...  # return content or raise KeyError
+
+    def upsert_file(self, project_id: str, filename: str, content: str) -> None:
+        ...
+
+    def delete_file(self, project_id: str, filename: str) -> None:
+        ...  # raise KeyError if not found
+```
+
+2. Add a factory function below the existing ones:
+
+```python
+def NewPlatform(project_id: str, *, ...) -> KnowledgeFiles:
+    return KnowledgeFiles(NewPlatformProvider(...), project_id=project_id)
+```
+
+3. Export from `aikb/__init__.py`.
+4. Add to the `_get_store` dispatch in `aikb/mcp_server.py`.
+5. Add optional dep group in `pyproject.toml` if needed.
+6. Add tests in `tests/test_aikb.py`.
+
+## Design rules
+
+- **Provider methods raise `KeyError`** on missing files, not `FileNotFoundError`.
+- **`list_files` and `__iter__` yield** — never return lists.
+- **Optional deps are lazy-imported** at method-call time, not at module import. Use `_check_dependency()` to give informative install hints.
+- **`functools.cached_property`** for expensive client initialization (e.g., API clients).
+- **No inheritance required** for providers — the `KnowledgeBaseProvider` Protocol uses structural subtyping.
+- All arguments after the first positional MUST be keyword-only.
+
+## Testing
+
+```bash
+pytest tests/ -v               # unit tests
+pytest --doctest-modules aikb/  # doctests
+```
+
+- `LocalFilesProvider` tests use the `tmp_path` fixture (no cleanup needed).
+- Provider tests for external platforms use `pytest.importorskip()`.
+- Integration tests requiring real credentials should be marked `@pytest.mark.integration`.
+
+## Extending KnowledgeMall
+
+`KnowledgeMall` is a `Mapping[str, KnowledgeFiles]`. To add declarative config-based construction, add a `@classmethod` factory. Keep the constructor signature simple: `KnowledgeMall(dict_or_kwargs)`.
+
+## MCP server
+
+The MCP server is a thin dispatch layer. When adding a new platform:
+1. Add an `elif` branch to `_get_store()` in `mcp_server.py`
+2. The tool functions themselves don't change — they delegate to `_get_store()`

aikb-0.0.2/.claude/skills/aikb-setup/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: aikb-setup
+description: "Use when helping a user install, configure, or start using aikb. Covers installation, authentication setup, first-use walkthroughs, and troubleshooting."
+---
+
+# aikb: Setup and Usage Guide
+
+Use this skill when helping someone install aikb, configure authentication, or get started with their first knowledge base operations.
+
+## Installation
+
+### Basic (local files only, zero extra deps)
+
+```bash
+pip install aikb
+```
+
+### With Claude Projects support
+
+```bash
+pip install aikb[claude]
+```
+
+### With MCP server
+
+```bash
+pip install aikb[mcp]
+```
+
+### Everything
+
+```bash
+pip install aikb[all]
+```
+
+## First use: Local files
+
+The fastest way to try aikb — no configuration needed:
+
+```python
+from aikb import LocalFiles
+
+store = LocalFiles('/path/to/knowledge_base')
+
+# Write files
+store['context.md'] = '# Project Context\nThis project does...'
+store['api-notes.md'] = '# API Notes\nEndpoint documentation...'
+
+# List files
+print(list(store))  # ['api-notes.md', 'context.md']
+
+# Read a file
+print(store['context.md'])
+
+# Delete a file
+del store['api-notes.md']
+```
+
+Files are stored as UTF-8 text in `{rootdir}/{project_id}/`. The default `project_id` is `'default'`.
+
+## Setting up Claude Projects access
+
+### Step 1: Get your session key
+
+1. Open https://claude.ai in your browser
+2. Open Developer Tools (F12) → Application → Cookies
+3. Copy the value of the `sessionKey` cookie (starts with `sk-ant-`)
+
+### Step 2: Configure authentication
+
+**Option A — Environment variable (recommended):**
+
+```bash
+export CLAUDE_SESSION_KEY='sk-ant-sid01-...'
+```
+
+Then in Python:
+
+```python
+from aikb import ClaudeProject
+store = ClaudeProject('your-project-uuid')
+```
+
+**Option B — Explicit parameter:**
+
+```python
+store = ClaudeProject('your-project-uuid', session_key='sk-ant-sid01-...')
+```
+
+**Option C — ClaudeSync config:**
+
+If you've already configured ClaudeSync (`claudesync auth login`), aikb will use its stored credentials automatically.
+
+### Step 3: Find your project UUID
+
+Project UUIDs are visible in the Claude.ai URL when you open a project:
+`https://claude.ai/project/{project-uuid}`
+
+## Setting up the MCP server
+
+### For Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aikb": {
+      "command": "python",
+      "args": ["-m", "aikb.mcp_server"]
+    }
+  }
+}
+```
+
+### For Claude Code
+
+```bash
+claude mcp add aikb -- python -m aikb.mcp_server
+```
+
+### Standalone
+
+```bash
+python -m aikb.mcp_server
+```
+
+## Multi-project setup
+
+```python
+from aikb import LocalFiles, ClaudeProject, KnowledgeMall
+
+mall = KnowledgeMall(
+    local=LocalFiles('/tmp/kb'),
+    project_a=ClaudeProject('uuid-a'),
+    project_b=ClaudeProject('uuid-b'),
+)
+
+# Access by name
+list(mall['local'])
+mall['project_a']['file.md'] = 'content'
+```
+
+## Troubleshooting
+
+### `ImportError: 'claudesync' is required`
+
+Install the Claude extras: `pip install aikb[claude]`
+
+### `ImportError: 'fastmcp' is required`
+
+Install the MCP extras: `pip install aikb[mcp]`
+
+### `KeyError` when reading a file
+
+The file doesn't exist in the project. Use `list(store)` to see available files, or `'filename' in store` to check.
+
+### Session key expired (403 errors)
+
+Claude.ai session keys expire periodically. Get a fresh one from your browser cookies and update `CLAUDE_SESSION_KEY`.
+
+### `ConnectionError` / `429` rate limiting
+
+ClaudeSync communicates with Claude.ai's internal API. Retry after a few seconds. Avoid rapid bulk operations.

aikb-0.0.2/.claude/skills/aikb-sync/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: aikb-sync
+description: "Use when syncing knowledge files between platforms or directories — e.g., pushing local files to Claude Projects, mirroring between projects, or batch-updating a knowledge base from a folder of markdown files."
+---
+
+# aikb: Sync Knowledge Files
+
+Use this skill when syncing, mirroring, or batch-managing knowledge files across platforms or directories.
+
+## Sync patterns
+
+### Push local files to Claude Project
+
+```python
+from aikb import LocalFiles, ClaudeProject
+
+local = LocalFiles('/path/to/docs')
+remote = ClaudeProject('project-uuid')
+
+# Push all files
+remote.update(local)
+
+# Push specific files
+for name in ['context.md', 'api.md']:
+    remote[name] = local[name]
+```
+
+### Pull from Claude Project to local
+
+```python
+local.update(remote)
+```
+
+### Mirror between two projects
+
+```python
+proj_a = ClaudeProject('uuid-a')
+proj_b = ClaudeProject('uuid-b')
+proj_b.update(proj_a)
+```
+
+### Selective sync with filtering
+
+```python
+# Only markdown files
+for name in local:
+    if name.endswith('.md'):
+        remote[name] = local[name]
+
+# Only files that differ
+for name in local:
+    if name not in remote or remote[name] != local[name]:
+        remote[name] = local[name]
+```
+
+### Delete remote files not present locally
+
+```python
+remote_only = set(remote) - set(local)
+for name in remote_only:
+    del remote[name]
+```
+
+## Helper script: sync_folder.py
+
+The script at `.claude/skills/aikb-sync/scripts/sync_folder.py` provides a
+ready-made sync operation:
+
+```bash
+# Dry run (show what would change)
+python .claude/skills/aikb-sync/scripts/sync_folder.py \
+  /path/to/local/docs project-uuid --dry-run
+
+# Actual sync
+python .claude/skills/aikb-sync/scripts/sync_folder.py \
+  /path/to/local/docs project-uuid
+
+# With explicit session key
+python .claude/skills/aikb-sync/scripts/sync_folder.py \
+  /path/to/local/docs project-uuid --session-key 'sk-ant-...'
+
+# Only .md files
+python .claude/skills/aikb-sync/scripts/sync_folder.py \
+  /path/to/local/docs project-uuid --glob '*.md'
+```
+
+## Workflow: Keep Claude Project in sync with a repo folder
+
+A common pattern is keeping a `docs/` or `knowledge/` folder in your repo
+synced with a Claude Project:
+
+```python
+from pathlib import Path
+from aikb import LocalFiles, ClaudeProject
+
+local = LocalFiles('knowledge')  # ./knowledge/default/
+remote = ClaudeProject('project-uuid')
+
+# Full bidirectional diff
+local_files = set(local)
+remote_files = set(remote)
+
+added = local_files - remote_files
+removed = remote_files - local_files
+common = local_files & remote_files
+changed = {f for f in common if local[f] != remote[f]}
+
+print(f"To add: {added}")
+print(f"To remove: {removed}")
+print(f"Changed: {changed}")
+
+# Apply
+for f in added | changed:
+    remote[f] = local[f]
+for f in removed:
+    del remote[f]
+```
+
+## Using KnowledgeMall for named sync pairs
+
+```python
+from aikb import LocalFiles, ClaudeProject, KnowledgeMall
+
+mall = KnowledgeMall(
+    staging=LocalFiles('/tmp/staging'),
+    prod=ClaudeProject('project-uuid'),
+)
+
+# Draft locally, review, then push
+mall['staging']['notes.md'] = '# Updated notes\n...'
+print(mall['staging']['notes.md'])  # review
+mall['prod']['notes.md'] = mall['staging']['notes.md']  # push
+```

aikb-0.0.2/.claude/skills/aikb-sync/scripts/sync_folder.py

@@ -0,0 +1,115 @@
+"""Sync a local folder to a Claude Project knowledge base.
+
+Usage:
+    python sync_folder.py /path/to/docs PROJECT_UUID [--dry-run] [--session-key SK] [--glob PATTERN]
+
+Examples:
+    # Dry run
+    python sync_folder.py ./knowledge proj-uuid --dry-run
+
+    # Actual sync
+    python sync_folder.py ./knowledge proj-uuid
+
+    # Only .md files
+    python sync_folder.py ./knowledge proj-uuid --glob '*.md'
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import sys
+
+
+def sync_folder(
+    local_dir: str,
+    project_id: str,
+    *,
+    session_key: str | None = None,
+    glob_pattern: str | None = None,
+    dry_run: bool = False,
+    delete_remote_extras: bool = False,
+):
+    """Sync local files to a Claude Project.
+
+    Returns a dict summarizing what was (or would be) done.
+    """
+    from aikb import LocalFiles, ClaudeProject
+
+    local = LocalFiles(local_dir, project_id="default")
+    remote = ClaudeProject(project_id, session_key=session_key)
+
+    local_files = set(local)
+    if glob_pattern:
+        local_files = {f for f in local_files if fnmatch.fnmatch(f, glob_pattern)}
+
+    remote_files = set(remote)
+
+    to_add = local_files - remote_files
+    to_remove = remote_files - local_files if delete_remote_extras else set()
+    common = local_files & remote_files
+    to_update = {f for f in common if local[f] != remote[f]}
+    unchanged = common - to_update
+
+    summary = {
+        "add": sorted(to_add),
+        "update": sorted(to_update),
+        "remove": sorted(to_remove),
+        "unchanged": sorted(unchanged),
+    }
+
+    if dry_run:
+        print("=== DRY RUN ===")
+        for action, files in summary.items():
+            if files:
+                print(f"\n{action.upper()} ({len(files)}):")
+                for f in files:
+                    print(f"  {f}")
+        if not any(summary[k] for k in ("add", "update", "remove")):
+            print("\nNothing to do — already in sync.")
+        return summary
+
+    for f in to_add | to_update:
+        print(f"  {'ADD' if f in to_add else 'UPD'} {f}")
+        remote[f] = local[f]
+
+    for f in to_remove:
+        print(f"  DEL {f}")
+        del remote[f]
+
+    total = len(to_add) + len(to_update) + len(to_remove)
+    print(f"\nDone: {total} change(s) applied.")
+    return summary
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Sync a local folder to a Claude Project knowledge base."
+    )
+    parser.add_argument("local_dir", help="Path to local folder")
+    parser.add_argument("project_id", help="Claude Project UUID")
+    parser.add_argument("--session-key", help="Claude session key")
+    parser.add_argument(
+        "--glob", dest="glob_pattern", help="Filter files by glob pattern"
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Show what would change")
+    parser.add_argument(
+        "--delete-remote-extras",
+        action="store_true",
+        help="Delete remote files not present locally",
+    )
+    args = parser.parse_args()
+
+    sync_folder(
+        args.local_dir,
+        args.project_id,
+        session_key=args.session_key,
+        glob_pattern=args.glob_pattern,
+        dry_run=args.dry_run,
+        delete_remote_extras=args.delete_remote_extras,
+    )
+
+
+if __name__ == "__main__":
+    main()

aikb-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation