feat: add PageIndex SDK with local/cloud dual-mode support (#207)

pageindex/backend/protocol.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Protocol, Any, AsyncIterator, runtime_checkable
+
+from ..events import QueryEvent
+
+
+@dataclass
+class AgentTools:
+    """Structured container for agent tool configuration (local mode only)."""
+    function_tools: list[Any] = field(default_factory=list)
+    mcp_servers: list[Any] = field(default_factory=list)
+
+
+@runtime_checkable
+class Backend(Protocol):
+    # Collection management
+    def create_collection(self, name: str) -> None: ...
+    def get_or_create_collection(self, name: str) -> None: ...
+    def list_collections(self) -> list[str]: ...
+    def delete_collection(self, name: str) -> None: ...
+
+    # Document management
+    def add_document(self, collection: str, file_path: str) -> str: ...
+    def get_document(self, collection: str, doc_id: str, include_text: bool = False) -> dict: ...
+    def get_document_structure(self, collection: str, doc_id: str) -> list: ...
+    def get_page_content(self, collection: str, doc_id: str, pages: str) -> list: ...
+    def list_documents(self, collection: str) -> list[dict]: ...
+    def delete_document(self, collection: str, doc_id: str) -> None: ...
+
+    # Query
+    def query(self, collection: str, question: str, doc_ids: list[str] | None = None) -> str: ...
+    async def query_stream(self, collection: str, question: str,
+                           doc_ids: list[str] | None = None) -> AsyncIterator[QueryEvent]: ...