okb 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

okb/migrations/0008.enrichment.sql

@@ -0,0 +1,46 @@
+-- LLM enrichment for document annotation (TODOs and entities)
+-- depends: 0006.llm-cache
+
+-- Track enrichment state on documents
+ALTER TABLE documents ADD COLUMN IF NOT EXISTS enriched_at TIMESTAMPTZ;
+ALTER TABLE documents ADD COLUMN IF NOT EXISTS enrichment_version INTEGER;
+
+-- Index for "needs enrichment" queries
+CREATE INDEX IF NOT EXISTS idx_documents_needs_enrichment
+    ON documents(enriched_at) WHERE enriched_at IS NULL;
+
+-- Pending entity suggestions (before approval)
+CREATE TABLE IF NOT EXISTS pending_entities (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    entity_name TEXT NOT NULL,
+    entity_type TEXT NOT NULL,  -- person, project, technology, concept, organization
+    aliases JSONB DEFAULT '[]',
+    description TEXT,
+    mentions JSONB DEFAULT '[]',  -- Context snippets from source document
+    confidence REAL,
+    status TEXT DEFAULT 'pending',  -- pending, approved, rejected
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    reviewed_at TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_pending_entities_status ON pending_entities(status);
+CREATE INDEX IF NOT EXISTS idx_pending_entities_source ON pending_entities(source_document_id);
+CREATE INDEX IF NOT EXISTS idx_pending_entities_type ON pending_entities(entity_type);
+
+-- Entity references (links entity documents to source documents)
+-- When an entity is approved, it becomes a document with source_path like okb://entity/person/john-smith
+-- This table tracks which documents mention each entity
+CREATE TABLE IF NOT EXISTS entity_refs (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    entity_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    mention_text TEXT NOT NULL,
+    context TEXT,  -- Surrounding text for context
+    confidence REAL,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(entity_id, document_id, mention_text)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_refs_entity ON entity_refs(entity_id);
+CREATE INDEX IF NOT EXISTS idx_entity_refs_document ON entity_refs(document_id);

okb/migrations/0009.entity-consolidation.sql

@@ -0,0 +1,120 @@
+-- Entity consolidation: deduplication, cross-doc detection, clustering, relationships
+-- depends: 0008.enrichment
+
+-- Canonical mappings: alias text -> entity document
+-- Used for deduplication and alias resolution
+CREATE TABLE IF NOT EXISTS entity_aliases (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    alias_text TEXT NOT NULL,
+    entity_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    confidence REAL,  -- How confident we are this alias belongs to entity
+    source TEXT DEFAULT 'manual',  -- 'manual', 'merge', 'extraction'
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(alias_text, entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_aliases_text ON entity_aliases(LOWER(alias_text));
+CREATE INDEX IF NOT EXISTS idx_entity_aliases_entity ON entity_aliases(entity_id);
+
+-- Proposed entity merges awaiting user confirmation
+CREATE TABLE IF NOT EXISTS pending_entity_merges (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    canonical_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    duplicate_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    confidence REAL NOT NULL,  -- How confident we are these are the same
+    reason TEXT,  -- Why we think they're the same ("embedding_similarity", "alias_match", "llm")
+    detected_at TIMESTAMPTZ DEFAULT NOW(),
+    status TEXT DEFAULT 'pending',  -- 'pending', 'approved', 'rejected'
+    reviewed_at TIMESTAMPTZ,
+    UNIQUE(canonical_id, duplicate_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pending_merges_status ON pending_entity_merges(status);
+CREATE INDEX IF NOT EXISTS idx_pending_merges_confidence ON pending_entity_merges(confidence DESC);
+
+-- Entity-to-entity relationships
+CREATE TABLE IF NOT EXISTS entity_relationships (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_entity_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    target_entity_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    relationship_type TEXT NOT NULL,  -- 'works_for', 'uses', 'belongs_to', 'related_to'
+    confidence REAL,
+    source TEXT DEFAULT 'extraction',  -- 'extraction', 'manual'
+    context TEXT,  -- Supporting context for the relationship
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(source_entity_id, target_entity_id, relationship_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_rel_source ON entity_relationships(source_entity_id);
+CREATE INDEX IF NOT EXISTS idx_entity_rel_target ON entity_relationships(target_entity_id);
+CREATE INDEX IF NOT EXISTS idx_entity_rel_type ON entity_relationships(relationship_type);
+
+-- Topic clusters group related entities and documents
+CREATE TABLE IF NOT EXISTS topic_clusters (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    description TEXT,
+    centroid vector(768),  -- Cluster centroid embedding
+    member_count INTEGER DEFAULT 0,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_topic_clusters_centroid ON topic_clusters
+    USING hnsw (centroid vector_cosine_ops);
+
+-- Cluster membership: entities and documents can belong to clusters
+CREATE TABLE IF NOT EXISTS topic_cluster_members (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    cluster_id UUID NOT NULL REFERENCES topic_clusters(id) ON DELETE CASCADE,
+    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    distance REAL,  -- Distance from cluster centroid
+    is_entity BOOLEAN DEFAULT FALSE,  -- True if document is an entity
+    added_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(cluster_id, document_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cluster_members_cluster ON topic_cluster_members(cluster_id);
+CREATE INDEX IF NOT EXISTS idx_cluster_members_document ON topic_cluster_members(document_id);
+
+-- Proposed cluster merges awaiting confirmation
+CREATE TABLE IF NOT EXISTS pending_cluster_merges (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    primary_cluster_id UUID NOT NULL REFERENCES topic_clusters(id) ON DELETE CASCADE,
+    secondary_cluster_id UUID NOT NULL REFERENCES topic_clusters(id) ON DELETE CASCADE,
+    similarity REAL NOT NULL,  -- How similar the clusters are
+    status TEXT DEFAULT 'pending',  -- 'pending', 'approved', 'rejected'
+    detected_at TIMESTAMPTZ DEFAULT NOW(),
+    reviewed_at TIMESTAMPTZ,
+    UNIQUE(primary_cluster_id, secondary_cluster_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pending_cluster_merges_status ON pending_cluster_merges(status);
+
+-- Cross-document entity candidates: detected mentions not yet extracted as entities
+CREATE TABLE IF NOT EXISTS cross_doc_entity_candidates (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    text TEXT NOT NULL,  -- The mention text (normalized)
+    document_ids UUID[] NOT NULL,  -- Array of document IDs containing this mention
+    document_count INTEGER NOT NULL,  -- Number of documents (for quick filtering)
+    sample_contexts JSONB DEFAULT '[]',  -- Sample text contexts where it appears
+    suggested_type TEXT,  -- Suggested entity type
+    confidence REAL,
+    status TEXT DEFAULT 'pending',  -- 'pending', 'approved', 'rejected', 'exists'
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    reviewed_at TIMESTAMPTZ,
+    UNIQUE(text)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cross_doc_status ON cross_doc_entity_candidates(status);
+CREATE INDEX IF NOT EXISTS idx_cross_doc_count ON cross_doc_entity_candidates(document_count DESC);
+
+-- Track consolidation runs
+CREATE TABLE IF NOT EXISTS consolidation_runs (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    run_type TEXT NOT NULL,  -- 'dedup', 'cross_doc', 'cluster', 'relationship', 'full'
+    started_at TIMESTAMPTZ DEFAULT NOW(),
+    completed_at TIMESTAMPTZ,
+    stats JSONB DEFAULT '{}',  -- Run statistics
+    error TEXT  -- Error message if failed
+);

okb/migrations/0010.token-id.sql

@@ -0,0 +1,7 @@
+-- Add ID column to tokens for easier revocation
+-- depends: 0009.entity-consolidation
+
+ALTER TABLE tokens ADD COLUMN IF NOT EXISTS id SERIAL;
+
+-- Create index for ID lookups
+CREATE INDEX IF NOT EXISTS tokens_id_idx ON tokens(id);

okb/modal_llm.py

@@ -2,20 +2,34 @@
 Modal-based GPU LLM service for document classification.
 
 Provides on-demand GPU access for LLM inference using open models.
-Uses Llama 3.2 3B by default - fast and efficient for classification tasks.
 
 Usage:
+    # Deploy with default model (Phi-3)
     modal deploy modal_llm.py
 
+    # Deploy with specific model
+    OKB_LLM_MODEL=meta-llama/Llama-3.2-3B-Instruct modal deploy modal_llm.py
+
 Then call from Python:
     llm = modal.Cls.from_name("knowledge-llm", "LLM")()
     response = llm.complete.remote("Classify this document", system="You are a classifier")
 """
 
+import os
+
 import modal
 
 app = modal.App("knowledge-llm")
 
+# Model is set via environment variable at deploy time
+# Default to Phi-3 which doesn't require HuggingFace approval
+DEFAULT_MODEL = "microsoft/Phi-3-mini-4k-instruct"
+MODEL_ID = os.environ.get("OKB_LLM_MODEL", DEFAULT_MODEL)
+
+# GPU type - L4 recommended for speed/cost balance
+DEFAULT_GPU = "L4"
+GPU_TYPE = os.environ.get("OKB_MODAL_GPU", DEFAULT_GPU)
+
 # Container image with transformers and torch
 llm_image = (
     modal.Image.debian_slim(python_version="3.11")
@@ -24,17 +38,19 @@ llm_image = (
         "torch>=2.0.0",
         "accelerate>=0.27.0",
         "bitsandbytes>=0.42.0",  # For quantization
+        "hf_transfer",  # Fast downloads
     )
-    .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
+    .env({
+        "HF_HUB_ENABLE_HF_TRANSFER": "1",
+        "OKB_LLM_MODEL": MODEL_ID,
+        "OKB_MODAL_GPU": GPU_TYPE,
+    })
 )
 
-# Default model - Llama 3.2 3B is fast and good for classification
-DEFAULT_MODEL = "meta-llama/Llama-3.2-3B-Instruct"
-
 
 @app.cls(
     image=llm_image,
-    gpu="T4",  # T4 is sufficient for 3B model with quantization
+    gpu=GPU_TYPE,
     timeout=300,
     scaledown_window=300,  # Keep warm for 5 min
     retries=1,
@@ -42,14 +58,16 @@ DEFAULT_MODEL = "meta-llama/Llama-3.2-3B-Instruct"
 class LLM:
     """GPU-accelerated LLM for document classification."""
 
-    model_id: str = DEFAULT_MODEL
-
     @modal.enter()
     def load_model(self):
         """Load model once when container starts."""
+        import os
+
         import torch
         from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
 
+        # Read model from environment (set at deploy time)
+        self.model_id = os.environ.get("OKB_LLM_MODEL", "microsoft/Phi-3-mini-4k-instruct")
         print(f"Loading model: {self.model_id}")
 
         # Use 4-bit quantization for memory efficiency

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/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/plugins/sources/github.py

@@ -95,11 +95,11 @@ class GitHubSource:
               token: ${GITHUB_TOKEN}
 
     Usage:
-        lkb sync run github --repo owner/repo              # README + docs/ (default)
-        lkb sync run github --repo owner/repo --source     # All source files
-        lkb sync run github --repo owner/repo --issues     # Include issues
-        lkb sync run github --repo owner/repo --prs        # Include PRs
-        lkb sync run github --repo owner/repo --wiki       # Include wiki
+        okb sync run github --repo owner/repo              # README + docs/ (default)
+        okb sync run github --repo owner/repo --source     # All source files
+        okb sync run github --repo owner/repo --issues     # Include issues
+        okb sync run github --repo owner/repo --prs        # Include PRs
+        okb sync run github --repo owner/repo --wiki       # Include wiki
     """
 
     name = "github"

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