okb 1.0.0__py3-none-any.whl

okb/plugins/registry.py

@@ -0,0 +1,123 @@
+"""Plugin discovery and registration via entry_points."""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import APISource, FileParser
+
+
+class PluginRegistry:
+    """Registry for file parsers and API sources discovered via entry_points.
+
+    Plugins are discovered from two entry_point groups:
+    - okb.parsers: FileParser implementations
+    - okb.sources: APISource implementations
+
+    Example pyproject.toml for a plugin:
+        [project.entry-points."okb.parsers"]
+        epub = "okb_epub:EpubParser"
+
+        [project.entry-points."okb.sources"]
+        github = "okb_github:GitHubSource"
+    """
+
+    _parsers: dict[str, list[FileParser]] = {}  # ext -> list of parsers
+    _sources: dict[str, APISource] = {}  # name -> source
+    _loaded = False
+
+    @classmethod
+    def load_plugins(cls) -> None:
+        """Load all plugins from entry_points. Called automatically on first use."""
+        if cls._loaded:
+            return
+
+        # Load file parsers
+        parser_eps = entry_points(group="okb.parsers")
+        for ep in parser_eps:
+            try:
+                parser_cls = ep.load()
+                parser = parser_cls()
+                for ext in parser.extensions:
+                    ext_lower = ext.lower()
+                    if ext_lower not in cls._parsers:
+                        cls._parsers[ext_lower] = []
+                    cls._parsers[ext_lower].append(parser)
+            except Exception as e:
+                print(f"Warning: Failed to load parser plugin '{ep.name}': {e}")
+
+        # Load API sources
+        source_eps = entry_points(group="okb.sources")
+        for ep in source_eps:
+            try:
+                source_cls = ep.load()
+                source = source_cls()
+                cls._sources[source.name] = source
+            except Exception as e:
+                print(f"Warning: Failed to load source plugin '{ep.name}': {e}")
+
+        cls._loaded = True
+
+    @classmethod
+    def get_parser_for_file(cls, path: Path) -> FileParser | None:
+        """Find a parser that can handle this file.
+
+        First filters by extension, then calls can_parse() on each candidate.
+
+        Args:
+            path: Path to the file to parse
+
+        Returns:
+            FileParser instance that can handle the file, or None
+        """
+        cls.load_plugins()
+        ext = path.suffix.lower()
+        for parser in cls._parsers.get(ext, []):
+            if parser.can_parse(path):
+                return parser
+        return None
+
+    @classmethod
+    def get_source(cls, name: str) -> APISource | None:
+        """Get an API source by name.
+
+        Args:
+            name: Source name (e.g., 'github', 'todoist')
+
+        Returns:
+            APISource instance, or None if not found
+        """
+        cls.load_plugins()
+        return cls._sources.get(name)
+
+    @classmethod
+    def list_sources(cls) -> list[str]:
+        """List all available API source names.
+
+        Returns:
+            List of source names
+        """
+        cls.load_plugins()
+        return list(cls._sources.keys())
+
+    @classmethod
+    def list_parsers(cls) -> dict[str, list[str]]:
+        """List all registered parsers by extension.
+
+        Returns:
+            Dict mapping extension to list of parser source_type names
+        """
+        cls.load_plugins()
+        return {
+            ext: [p.source_type for p in parsers] for ext, parsers in cls._parsers.items()
+        }
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the registry. Mainly useful for testing."""
+        cls._parsers = {}
+        cls._sources = {}
+        cls._loaded = False

okb/plugins/sources/__init__.py

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

okb/plugins/sources/dropbox_paper.py

@@ -0,0 +1,188 @@
+"""Dropbox Paper API source for syncing Paper documents as markdown."""
+
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from okb.ingest import Document
+    from okb.plugins.base import SyncState
+
+
+class DropboxPaperSource:
+    """API source for Dropbox Paper documents.
+
+    Syncs Paper documents as markdown for searchable knowledge base entries.
+
+    Config example:
+        plugins:
+          sources:
+            dropbox-paper:
+              enabled: true
+              token: ${DROPBOX_TOKEN}
+              folders: [/]  # Optional: filter to specific folder paths
+
+    Usage:
+        lkb sync run dropbox-paper
+        lkb sync run dropbox-paper --full  # Ignore incremental state
+    """
+
+    name = "dropbox-paper"
+    source_type = "dropbox-paper"
+
+    def __init__(self) -> None:
+        self._client = None
+        self._folders: list[str] | None = None
+        self._doc_ids: list[str] | None = None
+
+    def configure(self, config: dict) -> None:
+        """Initialize Dropbox client with OAuth token.
+
+        Args:
+            config: Source configuration containing 'token' and optional 'folders' or 'doc_ids'
+        """
+        import dropbox
+
+        token = config.get("token")
+        if not token:
+            raise ValueError("dropbox-paper source requires 'token' in config")
+
+        self._client = dropbox.Dropbox(token)
+        self._folders = config.get("folders")
+        self._doc_ids = config.get("doc_ids")  # Specific doc IDs from CLI
+
+    def fetch(self, state: SyncState | None = None) -> tuple[list[Document], SyncState]:
+        """Fetch Paper documents from Dropbox.
+
+        Uses the legacy Paper API to list and download documents as markdown.
+        Supports incremental sync via cursor-based pagination.
+
+        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] = []
+        cursor = state.cursor if state else None
+
+        print("Fetching Dropbox Paper documents...", file=sys.stderr)
+
+        # Use specific doc IDs from CLI, or list all Paper docs
+        if self._doc_ids:
+            doc_ids = self._doc_ids
+            print(f"Syncing {len(doc_ids)} specific document(s)", file=sys.stderr)
+        else:
+            doc_ids = self._list_paper_docs(cursor)
+            print(f"Found {len(doc_ids)} Paper documents", file=sys.stderr)
+
+        for doc_id in doc_ids:
+            try:
+                doc = self._fetch_paper_doc(doc_id)
+                if doc:
+                    # Apply folder filter if configured
+                    if self._folders:
+                        folder_path = doc.metadata.extra.get("folder_path", "/")
+                        if not any(folder_path.startswith(f) for f in self._folders):
+                            continue
+                    documents.append(doc)
+                    print(f"  Synced: {doc.title}", file=sys.stderr)
+            except Exception as e:
+                print(f"  Error fetching doc {doc_id}: {e}", file=sys.stderr)
+
+        # Build new sync state
+        new_state = SyncStateClass(
+            last_sync=datetime.now(UTC),
+            cursor=cursor,  # Paper API doesn't provide incremental cursors
+        )
+
+        return documents, new_state
+
+    def _list_paper_docs(self, cursor: str | None = None) -> list[str]:
+        """List all Paper document IDs.
+
+        Args:
+            cursor: Pagination cursor (not used by Paper API list)
+
+        Returns:
+            List of Paper document IDs
+        """
+
+        doc_ids = []
+
+        # Initial request
+        result = self._client.paper_docs_list()
+        doc_ids.extend(result.doc_ids)
+
+        # Paginate through all results
+        while result.has_more:
+            result = self._client.paper_docs_list_continue(result.cursor.value)
+            doc_ids.extend(result.doc_ids)
+
+        return doc_ids
+
+    def _fetch_paper_doc(self, doc_id: str) -> Document | None:
+        """Fetch a single Paper document and convert to Document.
+
+        Args:
+            doc_id: Dropbox Paper document ID
+
+        Returns:
+            Document instance or None if fetch failed
+        """
+        from dropbox.paper import ExportFormat
+
+        from okb.ingest import Document, DocumentMetadata
+
+        # Get document metadata
+        try:
+            folder_result = self._client.paper_docs_get_folder_info(doc_id)
+            folder_path = folder_result.folder_sharing_policy_type.name if folder_result else "/"
+            # Try to get actual folder path from folders list
+            if folder_result and hasattr(folder_result, "folders") and folder_result.folders:
+                folder_path = "/" + "/".join(f.name for f in folder_result.folders)
+            else:
+                folder_path = "/"
+        except Exception:
+            folder_path = "/"
+
+        # Download as markdown
+        result, response = self._client.paper_docs_download(
+            doc_id, ExportFormat.markdown
+        )
+
+        content = response.content.decode("utf-8")
+        if not content.strip():
+            return None
+
+        # Extract title from first heading or filename
+        title = result.title or f"Paper Doc {doc_id}"
+
+        # Parse modification time
+        doc_date = None
+        if hasattr(result, "server_modified"):
+            doc_date = result.server_modified.isoformat()
+
+        metadata = DocumentMetadata(
+            extra={
+                "folder_path": folder_path,
+                "doc_id": doc_id,
+            }
+        )
+        if doc_date:
+            metadata.extra["document_date"] = doc_date
+
+        return Document(
+            source_path=f"dropbox://paper/{doc_id}",
+            source_type=self.source_type,
+            title=title,
+            content=content,
+            metadata=metadata,
+        )