okb 1.0.0__tar.gz → 1.1.0a0__tar.gz

{okb-1.0.0 → okb-1.1.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: okb
-Version: 1.0.0
+Version: 1.1.0a0
 Summary: Personal knowledge base with semantic search for LLMs
 Requires-Python: >=3.11
 Classifier: Programming Language :: Python :: 3
@@ -13,6 +13,7 @@ Provides-Extra: docx
 Provides-Extra: llm
 Provides-Extra: llm-bedrock
 Provides-Extra: pdf
+Provides-Extra: todoist
 Provides-Extra: web
 Requires-Dist: PyGithub (>=2.0.0)
 Requires-Dist: anthropic (>=0.40.0) ; extra == "all"
@@ -35,10 +36,15 @@ Requires-Dist: python-docx (>=1.1.0) ; extra == "docx"
 Requires-Dist: pyyaml (>=6.0)
 Requires-Dist: ruff (>=0.1.0) ; extra == "dev"
 Requires-Dist: sentence-transformers (>=2.2.0)
+Requires-Dist: todoist-api-python (>=3.0.0) ; extra == "all"
+Requires-Dist: todoist-api-python (>=3.0.0) ; extra == "todoist"
 Requires-Dist: trafilatura (>=1.6.0) ; extra == "all"
 Requires-Dist: trafilatura (>=1.6.0) ; extra == "web"
 Requires-Dist: watchdog (>=3.0.0)
 Requires-Dist: yoyo-migrations (>=8.0.0)
+Project-URL: Homepage, https://github.com/username/okb
+Project-URL: Issues, https://github.com/username/okb/issues
+Project-URL: Repository, https://github.com/username/okb
 Description-Content-Type: text/markdown
 
 # Owned Knowledge Base (OKB)
@@ -47,15 +53,14 @@ A local-first semantic search system for personal documents with Claude Code int
 
 ## Installation
 
+pipx - preferred!
 ```bash
-pip install okb
+pipx install okb
 ```
 
-Or from source:
+Or pip:
 ```bash
-git clone https://github.com/yourusername/okb
-cd okb
-pip install -e .
+pip install okb
 ```
 
 ## Quick Start
@@ -82,7 +87,7 @@ okb ingest ~/notes ~/docs
 | `okb db status` | Show database status |
 | `okb db destroy` | Remove container and volume (destructive) |
 | `okb ingest <paths>` | Ingest documents into knowledge base |
-| `okb ingest <paths> --local` | Ingest using CPU embedding (no Modal) |
+| `okb ingest <paths> --local` | Ingest using local GPU/CPU embedding (no Modal) |
 | `okb serve` | Start MCP server (stdio, for Claude Code) |
 | `okb serve --http` | Start HTTP MCP server with token auth |
 | `okb watch <paths>` | Watch directories for changes |
@@ -93,7 +98,9 @@ okb ingest ~/notes ~/docs
 | `okb token list` | List tokens for a database |
 | `okb token revoke` | Revoke an API token |
 | `okb sync list` | List available API sources (plugins) |
+| `okb sync list-projects <source>` | List projects from source (for config) |
 | `okb sync run <sources>` | Sync data from external APIs |
+| `okb sync auth <source>` | Interactive OAuth setup (e.g., dropbox-paper) |
 | `okb sync status` | Show last sync times |
 | `okb rescan` | Check indexed files for changes, re-ingest stale |
 | `okb rescan --dry-run` | Show what would change without executing |
@@ -102,36 +109,6 @@ okb ingest ~/notes ~/docs
 | `okb llm deploy` | Deploy Modal LLM for open model inference |
 | `okb llm clear-cache` | Clear LLM response cache |
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         INGESTION (Burst GPU)                       │
-│                                                                     │
-│  Local Files → Contextual Chunking → Modal (GPU T4) → pgvector     │
-│                                                                     │
-│  ~/notes/project-x/api-design.md                                   │
-│       ↓                                                             │
-│  "Document: API Design Notes                                        │
-│   Project: project-x                                                │
-│   Section: Authentication                                           │
-│   Content: Use JWT tokens with..."                                  │
-│       ↓                                                             │
-│  [0.23, -0.41, 0.87, ...]  → pgvector                              │
-└─────────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────────┐
-│                      RETRIEVAL (Always-on, Local)                   │
-│                                                                     │
-│  Claude Code → MCP Server → CPU Embedding → pgvector → Results     │
-│                                                                     │
-│  "How do I handle auth?"                                            │
-│       ↓                                                             │
-│  [0.19, -0.38, 0.91, ...]  (local CPU, ~300ms)                     │
-│       ↓                                                             │
-│  Cosine similarity search → Top 5 chunks with context              │
-└─────────────────────────────────────────────────────────────────────┘
-```
 
 ## Configuration
 
@@ -273,7 +250,7 @@ Then configure Claude Code to connect via SSE:
 }
 ```
 
-## MCP Tools (Available in Claude Code)
+## MCP Tools available to LLM
 
 | Tool | Purpose |
 |------|---------|
@@ -287,6 +264,11 @@ Then configure Claude Code to connect via SSE:
 | `save_knowledge` | Save knowledge from Claude for future reference |
 | `delete_knowledge` | Delete a Claude-saved knowledge entry |
 | `get_actionable_items` | Query tasks/events with structured filters |
+| `get_database_info` | Get database description, topics, and stats |
+| `set_database_description` | Update database description/topics (LLM can self-document) |
+| `add_todo` | Create a TODO item in the knowledge base |
+| `trigger_sync` | Sync API sources (Todoist, GitHub, Dropbox Paper) |
+| `trigger_rescan` | Check indexed files for changes and re-ingest |
 
 ## Contextual Chunking
 
@@ -309,32 +291,6 @@ project: student-app
 category: backend
 ---
 
-# Query Optimization
-
-Use `select_related()` for foreign keys...
-```
-
-## Cost Estimate
-
-| Component | Local | Cloud Alternative |
-|-----------|-------|-------------------|
-| pgvector | $0 | ~$15-30/mo (CloudSQL) |
-| MCP Server | $0 | ~$5/mo (small VM) |
-| Modal embedding | ~$0.50-2/mo | N/A |
-| **Total** | **~$1-2/mo** | **~$20-35/mo** |
-
-## Development
-
-```bash
-# Install dev dependencies
-pip install -e ".[dev]"
-
-# Run tests
-pytest
-
-# Lint and format
-ruff check . && ruff format .
-```
 
 ## Plugin System
 
@@ -385,12 +341,30 @@ plugins:
       enabled: true
       token: ${GITHUB_TOKEN}  # Resolved from environment
       repos: [owner/repo1, owner/repo2]
+    todoist:
+      enabled: true
+      token: ${TODOIST_TOKEN}
+      include_completed: false     # Sync completed tasks
+      completed_days: 30           # Days of completed history
+      include_comments: false      # Include task comments (1 API call per task)
+      project_filter: []           # List of project IDs (use sync list-projects to find)
     dropbox-paper:
       enabled: true
-      token: ${DROPBOX_TOKEN}
+      # Option 1: Refresh token (recommended, auto-refreshes)
+      app_key: ${DROPBOX_APP_KEY}
+      app_secret: ${DROPBOX_APP_SECRET}
+      refresh_token: ${DROPBOX_REFRESH_TOKEN}
+      # Option 2: Access token (short-lived, expires after ~4 hours)
+      # token: ${DROPBOX_TOKEN}
       folders: [/]            # Optional: filter to specific folders
 ```
 
+**Dropbox Paper OAuth Setup:**
+```bash
+okb sync auth dropbox-paper
+```
+This interactive command will guide you through getting a refresh token from Dropbox.
+
 ## License
 
 MIT

{okb-1.0.0 → okb-1.1.0a0}/README.md

@@ -4,15 +4,14 @@ A local-first semantic search system for personal documents with Claude Code int
 
 ## Installation
 
+pipx - preferred!
 ```bash
-pip install okb
+pipx install okb
 ```
 
-Or from source:
+Or pip:
 ```bash
-git clone https://github.com/yourusername/okb
-cd okb
-pip install -e .
+pip install okb
 ```
 
 ## Quick Start
@@ -39,7 +38,7 @@ okb ingest ~/notes ~/docs
 | `okb db status` | Show database status |
 | `okb db destroy` | Remove container and volume (destructive) |
 | `okb ingest <paths>` | Ingest documents into knowledge base |
-| `okb ingest <paths> --local` | Ingest using CPU embedding (no Modal) |
+| `okb ingest <paths> --local` | Ingest using local GPU/CPU embedding (no Modal) |
 | `okb serve` | Start MCP server (stdio, for Claude Code) |
 | `okb serve --http` | Start HTTP MCP server with token auth |
 | `okb watch <paths>` | Watch directories for changes |
@@ -50,7 +49,9 @@ okb ingest ~/notes ~/docs
 | `okb token list` | List tokens for a database |
 | `okb token revoke` | Revoke an API token |
 | `okb sync list` | List available API sources (plugins) |
+| `okb sync list-projects <source>` | List projects from source (for config) |
 | `okb sync run <sources>` | Sync data from external APIs |
+| `okb sync auth <source>` | Interactive OAuth setup (e.g., dropbox-paper) |
 | `okb sync status` | Show last sync times |
 | `okb rescan` | Check indexed files for changes, re-ingest stale |
 | `okb rescan --dry-run` | Show what would change without executing |
@@ -59,36 +60,6 @@ okb ingest ~/notes ~/docs
 | `okb llm deploy` | Deploy Modal LLM for open model inference |
 | `okb llm clear-cache` | Clear LLM response cache |
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         INGESTION (Burst GPU)                       │
-│                                                                     │
-│  Local Files → Contextual Chunking → Modal (GPU T4) → pgvector     │
-│                                                                     │
-│  ~/notes/project-x/api-design.md                                   │
-│       ↓                                                             │
-│  "Document: API Design Notes                                        │
-│   Project: project-x                                                │
-│   Section: Authentication                                           │
-│   Content: Use JWT tokens with..."                                  │
-│       ↓                                                             │
-│  [0.23, -0.41, 0.87, ...]  → pgvector                              │
-└─────────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────────┐
-│                      RETRIEVAL (Always-on, Local)                   │
-│                                                                     │
-│  Claude Code → MCP Server → CPU Embedding → pgvector → Results     │
-│                                                                     │
-│  "How do I handle auth?"                                            │
-│       ↓                                                             │
-│  [0.19, -0.38, 0.91, ...]  (local CPU, ~300ms)                     │
-│       ↓                                                             │
-│  Cosine similarity search → Top 5 chunks with context              │
-└─────────────────────────────────────────────────────────────────────┘
-```
 
 ## Configuration
 
@@ -230,7 +201,7 @@ Then configure Claude Code to connect via SSE:
 }
 ```
 
-## MCP Tools (Available in Claude Code)
+## MCP Tools available to LLM
 
 | Tool | Purpose |
 |------|---------|
@@ -244,6 +215,11 @@ Then configure Claude Code to connect via SSE:
 | `save_knowledge` | Save knowledge from Claude for future reference |
 | `delete_knowledge` | Delete a Claude-saved knowledge entry |
 | `get_actionable_items` | Query tasks/events with structured filters |
+| `get_database_info` | Get database description, topics, and stats |
+| `set_database_description` | Update database description/topics (LLM can self-document) |
+| `add_todo` | Create a TODO item in the knowledge base |
+| `trigger_sync` | Sync API sources (Todoist, GitHub, Dropbox Paper) |
+| `trigger_rescan` | Check indexed files for changes and re-ingest |
 
 ## Contextual Chunking
 
@@ -266,32 +242,6 @@ project: student-app
 category: backend
 ---
 
-# Query Optimization
-
-Use `select_related()` for foreign keys...
-```
-
-## Cost Estimate
-
-| Component | Local | Cloud Alternative |
-|-----------|-------|-------------------|
-| pgvector | $0 | ~$15-30/mo (CloudSQL) |
-| MCP Server | $0 | ~$5/mo (small VM) |
-| Modal embedding | ~$0.50-2/mo | N/A |
-| **Total** | **~$1-2/mo** | **~$20-35/mo** |
-
-## Development
-
-```bash
-# Install dev dependencies
-pip install -e ".[dev]"
-
-# Run tests
-pytest
-
-# Lint and format
-ruff check . && ruff format .
-```
 
 ## Plugin System
 
@@ -342,12 +292,30 @@ plugins:
       enabled: true
       token: ${GITHUB_TOKEN}  # Resolved from environment
       repos: [owner/repo1, owner/repo2]
+    todoist:
+      enabled: true
+      token: ${TODOIST_TOKEN}
+      include_completed: false     # Sync completed tasks
+      completed_days: 30           # Days of completed history
+      include_comments: false      # Include task comments (1 API call per task)
+      project_filter: []           # List of project IDs (use sync list-projects to find)
     dropbox-paper:
       enabled: true
-      token: ${DROPBOX_TOKEN}
+      # Option 1: Refresh token (recommended, auto-refreshes)
+      app_key: ${DROPBOX_APP_KEY}
+      app_secret: ${DROPBOX_APP_SECRET}
+      refresh_token: ${DROPBOX_REFRESH_TOKEN}
+      # Option 2: Access token (short-lived, expires after ~4 hours)
+      # token: ${DROPBOX_TOKEN}
       folders: [/]            # Optional: filter to specific folders
 ```
 
+**Dropbox Paper OAuth Setup:**
+```bash
+okb sync auth dropbox-paper
+```
+This interactive command will guide you through getting a refresh token from Dropbox.
+
 ## License
 
 MIT

{okb-1.0.0 → okb-1.1.0a0}/okb/cli.py

@@ -968,6 +968,132 @@ def sync_list():
             click.echo(f"  {name}")
 
 
+@sync.command("list-projects")
+@click.argument("source")
+def sync_list_projects(source: str):
+    """List projects from an API source (for finding project IDs).
+
+    Example: okb sync list-projects todoist
+    """
+    from .plugins.registry import PluginRegistry
+
+    # Get the plugin
+    source_obj = PluginRegistry.get_source(source)
+    if source_obj is None:
+        click.echo(f"Error: Source '{source}' not found.", err=True)
+        click.echo(f"Installed sources: {', '.join(PluginRegistry.list_sources())}")
+        sys.exit(1)
+
+    # Check if source supports list_projects
+    if not hasattr(source_obj, "list_projects"):
+        click.echo(f"Error: Source '{source}' does not support listing projects.", err=True)
+        sys.exit(1)
+
+    # Get and resolve config
+    source_cfg = config.get_source_config(source)
+    if source_cfg is None:
+        click.echo(f"Error: Source '{source}' not configured.", err=True)
+        click.echo("Add it to your config file under plugins.sources")
+        sys.exit(1)
+
+    try:
+        source_obj.configure(source_cfg)
+    except Exception as e:
+        click.echo(f"Error configuring '{source}': {e}", err=True)
+        sys.exit(1)
+
+    try:
+        projects = source_obj.list_projects()
+        if projects:
+            click.echo(f"Projects in {source}:")
+            for project_id, name in projects:
+                click.echo(f"  {project_id}: {name}")
+        else:
+            click.echo("No projects found.")
+    except Exception as e:
+        click.echo(f"Error listing projects: {e}", err=True)
+        sys.exit(1)
+
+
+@sync.command("auth")
+@click.argument("source")
+def sync_auth(source: str):
+    """Authenticate with an API source (get tokens).
+
+    Currently supports: dropbox-paper
+
+    Example: okb sync auth dropbox-paper
+    """
+    if source == "dropbox-paper":
+        _auth_dropbox()
+    else:
+        click.echo(f"Error: Authentication helper not available for '{source}'", err=True)
+        click.echo("Supported: dropbox-paper")
+        sys.exit(1)
+
+
+def _auth_dropbox():
+    """Interactive OAuth flow for Dropbox."""
+    try:
+        import dropbox
+        from dropbox import DropboxOAuth2FlowNoRedirect
+    except ImportError:
+        click.echo("Error: dropbox package not installed", err=True)
+        click.echo("Install with: pip install dropbox", err=True)
+        sys.exit(1)
+
+    click.echo("Dropbox OAuth Setup")
+    click.echo("=" * 50)
+    click.echo("")
+    click.echo("You'll need your Dropbox app credentials.")
+    click.echo("Get them at: https://www.dropbox.com/developers/apps")
+    click.echo("")
+
+    app_key = click.prompt("App key")
+    app_secret = click.prompt("App secret")
+
+    # Start OAuth flow
+    auth_flow = DropboxOAuth2FlowNoRedirect(
+        app_key,
+        app_secret,
+        token_access_type="offline",  # This gives us a refresh token
+    )
+
+    authorize_url = auth_flow.start()
+    click.echo("")
+    click.echo("1. Go to this URL in your browser:")
+    click.echo(f"   {authorize_url}")
+    click.echo("")
+    click.echo("2. Click 'Allow' to authorize the app")
+    click.echo("3. Copy the authorization code")
+    click.echo("")
+
+    auth_code = click.prompt("Enter the authorization code")
+
+    try:
+        oauth_result = auth_flow.finish(auth_code.strip())
+    except Exception as e:
+        click.echo(f"Error: Failed to get tokens - {e}", err=True)
+        sys.exit(1)
+
+    click.echo("")
+    click.echo("Success! Add these to your environment or config:")
+    click.echo("")
+    click.echo(f"DROPBOX_APP_KEY={app_key}")
+    click.echo(f"DROPBOX_APP_SECRET={app_secret}")
+    click.echo(f"DROPBOX_REFRESH_TOKEN={oauth_result.refresh_token}")
+    click.echo("")
+    click.echo("Config example (~/.config/okb/config.yaml):")
+    click.echo("")
+    click.echo("plugins:")
+    click.echo("  sources:")
+    click.echo("    dropbox-paper:")
+    click.echo("      enabled: true")
+    click.echo("      app_key: ${DROPBOX_APP_KEY}")
+    click.echo("      app_secret: ${DROPBOX_APP_SECRET}")
+    click.echo("      refresh_token: ${DROPBOX_REFRESH_TOKEN}")
+
+
 @sync.command("status")
 @click.argument("source", required=False)
 @click.option("--db", "database", default=None, help="Database to check")

{okb-1.0.0 → okb-1.1.0a0}/okb/http_server.py

@@ -49,6 +49,8 @@ WRITE_TOOLS = frozenset(
         "delete_knowledge",
         "set_database_description",
         "add_todo",
+        "trigger_sync",
+        "trigger_rescan",
     }
 )
 
@@ -349,6 +351,49 @@ class HTTPMCPServer:
                     content=[TextContent(type="text", text="No fields provided to update.")]
                 )
 
+            elif name == "add_todo":
+                result = kb.save_todo(
+                    title=arguments["title"],
+                    content=arguments.get("content"),
+                    due_date=arguments.get("due_date"),
+                    priority=arguments.get("priority"),
+                    project=arguments.get("project"),
+                    tags=arguments.get("tags"),
+                )
+                parts = [
+                    "TODO created:",
+                    f"- Title: {result['title']}",
+                    f"- Path: `{result['source_path']}`",
+                ]
+                if result.get("priority"):
+                    parts.append(f"- Priority: P{result['priority']}")
+                if result.get("due_date"):
+                    parts.append(f"- Due: {result['due_date']}")
+                return CallToolResult(content=[TextContent(type="text", text="\n".join(parts))])
+
+            elif name == "trigger_sync":
+                from .mcp_server import _run_sync
+
+                # Get the db_url from the knowledge base
+                result = _run_sync(
+                    kb.db_url,
+                    sources=arguments.get("sources", []),
+                    sync_all=arguments.get("all", False),
+                    full=arguments.get("full", False),
+                    doc_ids=arguments.get("doc_ids"),
+                )
+                return CallToolResult(content=[TextContent(type="text", text=result)])
+
+            elif name == "trigger_rescan":
+                from .mcp_server import _run_rescan
+
+                result = _run_rescan(
+                    kb.db_url,
+                    dry_run=arguments.get("dry_run", False),
+                    delete_missing=arguments.get("delete_missing", False),
+                )
+                return CallToolResult(content=[TextContent(type="text", text=result)])
+
             else:
                 return CallToolResult(
                     content=[TextContent(type="text", text=f"Unknown tool: {name}")]

{okb-1.0.0 → okb-1.1.0a0}/okb/mcp_server.py

@@ -676,6 +676,170 @@ class KnowledgeBase:
         return [dict(r) for r in results]
 
 
+def _get_sync_state(conn, source_name: str, db_name: str):
+    """Get sync state from database."""
+    from .plugins.base import SyncState
+
+    result = conn.execute(
+        """SELECT last_sync, cursor, extra FROM sync_state
+           WHERE source_name = %s AND database_name = %s""",
+        (source_name, db_name),
+    ).fetchone()
+
+    if result:
+        return SyncState(
+            last_sync=result["last_sync"],
+            cursor=result["cursor"],
+            extra=result["extra"] or {},
+        )
+    return None
+
+
+def _save_sync_state(conn, source_name: str, db_name: str, state):
+    """Save sync state to database."""
+    import json
+
+    conn.execute(
+        """INSERT INTO sync_state (source_name, database_name, last_sync, cursor, extra, updated_at)
+           VALUES (%s, %s, %s, %s, %s, NOW())
+           ON CONFLICT (source_name, database_name)
+           DO UPDATE SET last_sync = EXCLUDED.last_sync,
+                        cursor = EXCLUDED.cursor,
+                        extra = EXCLUDED.extra,
+                        updated_at = NOW()""",
+        (source_name, db_name, state.last_sync, state.cursor, json.dumps(state.extra)),
+    )
+    conn.commit()
+
+
+def _run_sync(
+    db_url: str,
+    sources: list[str],
+    sync_all: bool = False,
+    full: bool = False,
+    doc_ids: list[str] | None = None,
+) -> str:
+    """Run sync for specified sources and return formatted result."""
+    from psycopg.rows import dict_row
+
+    from .ingest import Ingester
+    from .plugins.registry import PluginRegistry
+
+    # Determine which sources to sync
+    if sync_all:
+        source_names = config.list_enabled_sources()
+    elif sources:
+        source_names = list(sources)
+    else:
+        # Return list of available sources
+        installed = PluginRegistry.list_sources()
+        configured = config.list_enabled_sources()
+        lines = ["Available API sources:"]
+        for name in installed:
+            status = "enabled" if name in configured else "disabled"
+            lines.append(f"  - {name} ({status})")
+        if not installed:
+            lines.append("  (none installed)")
+        return "\n".join(lines)
+
+    if not source_names:
+        return "No sources to sync."
+
+    # Get database name from URL for sync state
+    db_name = config.get_database().name
+
+    results = []
+    ingester = Ingester(db_url, use_modal=True)
+
+    with psycopg.connect(db_url, row_factory=dict_row) as conn:
+        for source_name in source_names:
+            # Get the plugin
+            source = PluginRegistry.get_source(source_name)
+            if source is None:
+                results.append(f"{source_name}: not found")
+                continue
+
+            # Get and resolve config
+            source_cfg = config.get_source_config(source_name)
+            if source_cfg is None:
+                results.append(f"{source_name}: not configured or disabled")
+                continue
+
+            # Inject doc_ids if provided (for sources that support it)
+            if doc_ids:
+                source_cfg = {**source_cfg, "doc_ids": doc_ids}
+
+            try:
+                source.configure(source_cfg)
+            except Exception as e:
+                results.append(f"{source_name}: config error - {e}")
+                continue
+
+            # Get sync state (unless full)
+            state = None if full else _get_sync_state(conn, source_name, db_name)
+
+            try:
+                documents, new_state = source.fetch(state)
+            except Exception as e:
+                results.append(f"{source_name}: fetch error - {e}")
+                continue
+
+            if documents:
+                ingester.ingest_documents(documents)
+                results.append(f"{source_name}: synced {len(documents)} documents")
+            else:
+                results.append(f"{source_name}: no new documents")
+
+            # Save state
+            _save_sync_state(conn, source_name, db_name, new_state)
+
+    return "\n".join(results)
+
+
+def _run_rescan(
+    db_url: str,
+    dry_run: bool = False,
+    delete_missing: bool = False,
+) -> str:
+    """Run rescan and return formatted result."""
+    from .rescan import Rescanner
+
+    rescanner = Rescanner(db_url, use_modal=True)
+    result = rescanner.rescan(dry_run=dry_run, delete_missing=delete_missing, verbose=False)
+
+    lines = []
+    if dry_run:
+        lines.append("(dry run - no changes made)")
+
+    if result.updated:
+        lines.append(f"Updated: {len(result.updated)} files")
+        for path in result.updated[:5]:  # Show first 5
+            lines.append(f"  - {path}")
+        if len(result.updated) > 5:
+            lines.append(f"  ... and {len(result.updated) - 5} more")
+
+    if result.deleted:
+        lines.append(f"Deleted: {len(result.deleted)} files")
+
+    if result.missing:
+        lines.append(f"Missing (not deleted): {len(result.missing)} files")
+        for path in result.missing[:5]:
+            lines.append(f"  - {path}")
+        if len(result.missing) > 5:
+            lines.append(f"  ... and {len(result.missing) - 5} more")
+
+    lines.append(f"Unchanged: {result.unchanged} files")
+
+    if result.errors:
+        lines.append(f"Errors: {len(result.errors)}")
+        for path, error in result.errors[:3]:
+            lines.append(f"  - {path}: {error}")
+        if len(result.errors) > 3:
+            lines.append(f"  ... and {len(result.errors) - 3} more")
+
+    return "\n".join(lines) if lines else "No indexed files found."
+
+
 def build_server_instructions(db_config) -> str | None:
     """Build server instructions from database config and LLM metadata."""
     parts = []
@@ -1025,6 +1189,67 @@ async def list_tools() -> list[Tool]:
                 "required": ["title"],
             },
         ),
+        Tool(
+            name="trigger_sync",
+            description=(
+                "Trigger sync of API sources (Todoist, GitHub, Dropbox Paper, etc.). "
+                "Fetches new/updated content from external services. Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sources": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "List of source names to sync (e.g., ['todoist', 'github']). "
+                            "If empty and 'all' is false, returns list of available sources."
+                        ),
+                    },
+                    "all": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Sync all enabled sources",
+                    },
+                    "full": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Ignore incremental state and do full resync",
+                    },
+                    "doc_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Specific document IDs to sync (for dropbox-paper). "
+                            "If provided, only these documents are synced."
+                        ),
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="trigger_rescan",
+            description=(
+                "Check indexed files for changes and re-ingest stale ones. "
+                "Compares stored modification times with current filesystem. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "dry_run": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Only report what would change, don't actually re-ingest",
+                    },
+                    "delete_missing": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Remove documents for files that no longer exist",
+                    },
+                },
+            },
+        ),
     ]
 
 
@@ -1358,6 +1583,24 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
                 parts.append(f"- Due: {result['due_date']}")
             return CallToolResult(content=[TextContent(type="text", text="\n".join(parts))])
 
+        elif name == "trigger_sync":
+            result = _run_sync(
+                kb.db_url,
+                sources=arguments.get("sources", []),
+                sync_all=arguments.get("all", False),
+                full=arguments.get("full", False),
+                doc_ids=arguments.get("doc_ids"),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "trigger_rescan":
+            result = _run_rescan(
+                kb.db_url,
+                dry_run=arguments.get("dry_run", False),
+                delete_missing=arguments.get("delete_missing", False),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
         else:
             return CallToolResult(content=[TextContent(type="text", text=f"Unknown tool: {name}")])
 

{okb-1.0.0 → okb-1.1.0a0}/okb/plugins/sources/__init__.py

@@ -1,5 +1,6 @@
 """Built-in API source plugins for OKB."""
 
 from okb.plugins.sources.dropbox_paper import DropboxPaperSource
+from okb.plugins.sources.todoist import TodoistSource
 
-__all__ = ["DropboxPaperSource"]
+__all__ = ["DropboxPaperSource", "TodoistSource"]

{okb-1.0.0 → okb-1.1.0a0}/okb/plugins/sources/dropbox_paper.py

@@ -16,17 +16,27 @@ class DropboxPaperSource:
 
     Syncs Paper documents as markdown for searchable knowledge base entries.
 
-    Config example:
+    Config example (refresh token - recommended):
         plugins:
           sources:
             dropbox-paper:
               enabled: true
-              token: ${DROPBOX_TOKEN}
+              app_key: ${DROPBOX_APP_KEY}
+              app_secret: ${DROPBOX_APP_SECRET}
+              refresh_token: ${DROPBOX_REFRESH_TOKEN}
               folders: [/]  # Optional: filter to specific folder paths
 
+    Config example (access token - short-lived):
+        plugins:
+          sources:
+            dropbox-paper:
+              enabled: true
+              token: ${DROPBOX_TOKEN}  # Expires after ~4 hours
+
     Usage:
-        lkb sync run dropbox-paper
-        lkb sync run dropbox-paper --full  # Ignore incremental state
+        okb sync run dropbox-paper
+        okb sync run dropbox-paper --full  # Ignore incremental state
+        okb sync run dropbox-paper --doc <doc_id>  # Sync specific document
     """
 
     name = "dropbox-paper"
@@ -38,18 +48,43 @@ class DropboxPaperSource:
         self._doc_ids: list[str] | None = None
 
     def configure(self, config: dict) -> None:
-        """Initialize Dropbox client with OAuth token.
+        """Initialize Dropbox client with OAuth token or refresh token.
+
+        Supports two authentication modes:
+        1. Access token only (short-lived, will expire):
+           token: <access_token>
+
+        2. Refresh token (recommended, auto-refreshes):
+           app_key: <app_key>
+           app_secret: <app_secret>
+           refresh_token: <refresh_token>
 
         Args:
-            config: Source configuration containing 'token' and optional 'folders' or 'doc_ids'
+            config: Source configuration containing auth credentials and optional 'folders'/'doc_ids'
         """
         import dropbox
 
+        app_key = config.get("app_key")
+        app_secret = config.get("app_secret")
+        refresh_token = config.get("refresh_token")
         token = config.get("token")
-        if not token:
-            raise ValueError("dropbox-paper source requires 'token' in config")
 
-        self._client = dropbox.Dropbox(token)
+        if app_key and app_secret and refresh_token:
+            # Use refresh token - will auto-refresh access tokens
+            self._client = dropbox.Dropbox(
+                app_key=app_key,
+                app_secret=app_secret,
+                oauth2_refresh_token=refresh_token,
+            )
+        elif token:
+            # Legacy: direct access token (will expire)
+            self._client = dropbox.Dropbox(token)
+        else:
+            raise ValueError(
+                "dropbox-paper source requires either 'token' or "
+                "'app_key'/'app_secret'/'refresh_token' in config"
+            )
+
         self._folders = config.get("folders")
         self._doc_ids = config.get("doc_ids")  # Specific doc IDs from CLI
 

okb-1.1.0a0/okb/plugins/sources/todoist.py

@@ -0,0 +1,254 @@
+"""Todoist API source for syncing tasks into OKB."""
+
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from okb.ingest import Document
+    from okb.plugins.base import SyncState
+
+
+class TodoistSource:
+    """API source for Todoist tasks.
+
+    Syncs active and optionally completed tasks for semantic search and actionable item queries.
+
+    Config example:
+        plugins:
+          sources:
+            todoist:
+              enabled: true
+              token: ${TODOIST_TOKEN}
+              include_completed: false   # Include recently completed tasks
+              completed_days: 30         # Days of completed tasks to sync
+              include_comments: false    # Include task comments (expensive)
+              project_filter: []         # Optional: list of project IDs to sync
+
+    Usage:
+        okb sync run todoist
+        okb sync run todoist --full  # Full resync
+    """
+
+    name = "todoist"
+    source_type = "todoist-task"
+
+    def __init__(self) -> None:
+        self._client = None
+        self._include_completed = False
+        self._completed_days = 30
+        self._include_comments = False
+        self._project_filter: list[str] | None = None
+        self._projects: dict[str, str] = {}  # id -> name
+
+    def configure(self, config: dict) -> None:
+        """Initialize Todoist client with API token.
+
+        Args:
+            config: Source configuration containing 'token' and optional settings
+        """
+        from todoist_api_python.api import TodoistAPI
+
+        token = config.get("token")
+        if not token:
+            raise ValueError("todoist source requires 'token' in config")
+
+        self._client = TodoistAPI(token)
+        self._include_completed = config.get("include_completed", False)
+        self._completed_days = config.get("completed_days", 30)
+        self._include_comments = config.get("include_comments", False)
+        self._project_filter = config.get("project_filter")
+
+    def fetch(self, state: SyncState | None = None) -> tuple[list[Document], SyncState]:
+        """Fetch tasks from Todoist.
+
+        Active tasks are always fully synced (API has no "modified since" filter).
+        Completed tasks use state.last_sync for incremental fetching.
+
+        Args:
+            state: Previous sync state for incremental updates, or None for full sync
+
+        Returns:
+            Tuple of (list of documents, new sync state)
+        """
+        from okb.plugins.base import SyncState as SyncStateClass
+
+        if self._client is None:
+            raise RuntimeError("Source not configured. Call configure() first.")
+
+        documents: list[Document] = []
+
+        print("Fetching Todoist tasks...", file=sys.stderr)
+
+        # Load projects for name lookup
+        self._load_projects()
+
+        # Fetch active tasks
+        active_docs = self._fetch_active_tasks()
+        documents.extend(active_docs)
+        print(f"  Synced {len(active_docs)} active tasks", file=sys.stderr)
+
+        # Fetch completed tasks if enabled
+        if self._include_completed:
+            since = state.last_sync if state and state.last_sync else None
+            completed_docs = self._fetch_completed_tasks(since)
+            documents.extend(completed_docs)
+            print(f"  Synced {len(completed_docs)} completed tasks", file=sys.stderr)
+
+        new_state = SyncStateClass(last_sync=datetime.now(UTC))
+        return documents, new_state
+
+    def _load_projects(self) -> None:
+        """Load projects for name lookup."""
+        try:
+            self._projects = {}
+            for project_batch in self._client.get_projects():
+                for p in project_batch:
+                    self._projects[p.id] = p.name
+        except Exception as e:
+            print(f"  Warning: Could not load projects: {e}", file=sys.stderr)
+            self._projects = {}
+
+    def _fetch_active_tasks(self) -> list[Document]:
+        """Fetch all active tasks."""
+        documents = []
+
+        for task_batch in self._client.get_tasks():
+            for task in task_batch:
+                # Apply project filter if configured
+                if self._project_filter and task.project_id not in self._project_filter:
+                    continue
+
+                doc = self._task_to_document(task, is_completed=False)
+                if doc:
+                    documents.append(doc)
+
+        return documents
+
+    def _fetch_completed_tasks(self, since: datetime | None) -> list[Document]:
+        """Fetch completed tasks within the configured window."""
+        documents = []
+
+        # Determine date range
+        until = datetime.now(UTC)
+        if since:
+            start = since
+        else:
+            start = until - timedelta(days=self._completed_days)
+
+        try:
+            for task_batch in self._client.get_completed_tasks_by_completion_date(
+                since=start,
+                until=until,
+            ):
+                for task in task_batch:
+                    # Apply project filter if configured
+                    if self._project_filter and task.project_id not in self._project_filter:
+                        continue
+
+                    doc = self._task_to_document(task, is_completed=True)
+                    if doc:
+                        documents.append(doc)
+        except Exception as e:
+            print(f"  Warning: Could not fetch completed tasks: {e}", file=sys.stderr)
+
+        return documents
+
+    def _task_to_document(self, task, is_completed: bool) -> Document | None:
+        """Convert a Todoist task to a Document."""
+        from okb.ingest import Document, DocumentMetadata
+
+        # Build content from task content + description + optional comments
+        content_parts = [task.content]
+        if task.description:
+            content_parts.append(task.description)
+
+        if self._include_comments:
+            comments = self._fetch_task_comments(task.id)
+            if comments:
+                content_parts.append("\n## Comments\n" + "\n".join(comments))
+
+        content = "\n\n".join(content_parts)
+
+        # Parse due date
+        due_date = None
+        if task.due:
+            due_date = self._parse_due(task.due)
+
+        # Map priority: Todoist uses 1-4 (4=urgent), OKB uses 1-5 (1=highest)
+        priority = 5 - task.priority if task.priority else None
+
+        # Get project name
+        project_name = self._projects.get(task.project_id)
+
+        # Build metadata
+        metadata = DocumentMetadata(
+            tags=task.labels or [],
+            project=project_name,
+            extra={
+                "todoist_id": task.id,
+                "project_id": task.project_id,
+            },
+        )
+
+        # Determine status
+        status = "completed" if is_completed or task.is_completed else "pending"
+
+        return Document(
+            source_path=f"todoist://task/{task.id}",
+            source_type=self.source_type,
+            title=task.content,
+            content=content,
+            metadata=metadata,
+            due_date=due_date,
+            status=status,
+            priority=priority,
+        )
+
+    def _parse_due(self, due) -> datetime | None:
+        """Parse Todoist Due object to datetime."""
+        if due is None:
+            return None
+
+        try:
+            # Due has 'datetime' (full datetime) or 'date' (date only)
+            if hasattr(due, "datetime") and due.datetime:
+                return datetime.fromisoformat(due.datetime.replace("Z", "+00:00"))
+            elif hasattr(due, "date") and due.date:
+                # Date-only: treat as end of day in UTC
+                if isinstance(due.date, str):
+                    d = datetime.strptime(due.date, "%Y-%m-%d").date()
+                else:
+                    d = due.date
+                return datetime(d.year, d.month, d.day, 23, 59, 59, tzinfo=UTC)
+        except Exception:
+            pass
+        return None
+
+    def _fetch_task_comments(self, task_id: str) -> list[str]:
+        """Fetch comments for a task."""
+        comments = []
+        try:
+            for comment_batch in self._client.get_comments(task_id=task_id):
+                for comment in comment_batch:
+                    comments.append(f"- {comment.content}")
+        except Exception:
+            pass
+        return comments
+
+    def list_projects(self) -> list[tuple[str, str]]:
+        """List all projects with their IDs.
+
+        Returns:
+            List of (project_id, project_name) tuples
+        """
+        if self._client is None:
+            raise RuntimeError("Source not configured. Call configure() first.")
+
+        projects = []
+        for project_batch in self._client.get_projects():
+            for p in project_batch:
+                projects.append((p.id, p.name))
+        return projects

{okb-1.0.0 → okb-1.1.0a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "okb"
-version = "1.0.0"
+version = "1.1.0a0"
 description = "Personal knowledge base with semantic search for LLMs"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,6 +19,11 @@ dependencies = [
     "PyGithub>=2.0.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/username/okb"
+Repository = "https://github.com/username/okb"
+Issues = "https://github.com/username/okb/issues"
+
 [project.optional-dependencies]
 pdf = ["pymupdf>=1.23.0"]
 docx = ["python-docx>=1.1.0"]
@@ -29,11 +34,13 @@ llm-bedrock = [
       "boto3>=1.28.0",
       "botocore>=1.31.0",
   ]
+todoist = ["todoist-api-python>=3.0.0"]
 all = [
     "pymupdf>=1.23.0",
     "python-docx>=1.1.0",
     "trafilatura>=1.6.0",
     "anthropic>=0.40.0",
+    "todoist-api-python>=3.0.0",
 ]
 dev = [
     "pytest>=7.0.0",
@@ -59,6 +66,7 @@ okb = "okb.cli:main"
 # Built-in sources
 dropbox-paper = "okb.plugins.sources.dropbox_paper:DropboxPaperSource"
 github = "okb.plugins.sources.github:GitHubSource"
+todoist = "okb.plugins.sources.todoist:TodoistSource"
 # External plugins register additional API sources here
 
 [build-system]
@@ -68,6 +76,9 @@ build-backend = "poetry.core.masonry.api"
 [tool.poetry]
 packages = [{include = "okb"}]
 
+[tool.poetry.dependencies]
+python = ">=3.11,<4.0"
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"