cortexdb-py 0.1.0__tar.gz

cortexdb_py-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: cortexdb-py
+Version: 0.1.0
+Summary: Python SDK for CortexDB — a RAG-powered memory database
+Author: VectorNode
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: eval-type-backport (>=0.3.1,<0.4.0)
+Requires-Dist: google-genai (>=1.0.0,<2.0.0)
+Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+# CortexDB Python SDK
+
+A Python client for the CortexDB RAG backend, providing easy access to ingestion, querying, and LLM orchestration.
+
+## Features
+
+- **Setup API**: Configure LLM providers (Gemini, OpenAI, Azure).
+- **Ingest API**: Ingest documents with automatic embedding generation.
+- **Query API**: Perform semantic search, entity retrieval, and graph traversals.
+- **Native LLM Integration**: Uses `google-genai` for native Gemini support.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+See `main.py` for a complete example of setting up a medical chatbot.
+
+```python
+from cortexdb import CortexDB
+
+db = CortexDB("http://localhost:8080")
+
+# Setup
+db.setup.configure(provider="GEMINI", api_key="...", chat_model="gemini-2.0-flash", embed_model="gemini-embedding-001")
+
+# Ingest
+db.ingest.document(uid="user-1", converser="USER", content="Hello world")
+
+# Query
+results = db.query.search_contexts("Hello", limit=5)
+```
+
+## Testing
+
+```bash
+pip install pytest respx
+pytest tests/
+```
+

cortexdb_py-0.1.0/README.md

@@ -0,0 +1,42 @@
+# CortexDB Python SDK
+
+A Python client for the CortexDB RAG backend, providing easy access to ingestion, querying, and LLM orchestration.
+
+## Features
+
+- **Setup API**: Configure LLM providers (Gemini, OpenAI, Azure).
+- **Ingest API**: Ingest documents with automatic embedding generation.
+- **Query API**: Perform semantic search, entity retrieval, and graph traversals.
+- **Native LLM Integration**: Uses `google-genai` for native Gemini support.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+See `main.py` for a complete example of setting up a medical chatbot.
+
+```python
+from cortexdb import CortexDB
+
+db = CortexDB("http://localhost:8080")
+
+# Setup
+db.setup.configure(provider="GEMINI", api_key="...", chat_model="gemini-2.0-flash", embed_model="gemini-embedding-001")
+
+# Ingest
+db.ingest.document(uid="user-1", converser="USER", content="Hello world")
+
+# Query
+results = db.query.search_contexts("Hello", limit=5)
+```
+
+## Testing
+
+```bash
+pip install pytest respx
+pytest tests/
+```

cortexdb_py-0.1.0/cortexdb/__init__.py

@@ -0,0 +1,7 @@
+"""CortexDB Python SDK — A RAG-powered memory database client."""
+
+from cortexdb.client import CortexDB
+from cortexdb.llm.provider import LLMProvider
+
+__all__ = ["CortexDB", "LLMProvider"]
+__version__ = "0.1.0"

cortexdb_py-0.1.0/cortexdb/client.py

@@ -0,0 +1,70 @@
+"""Main CortexDB client — entry point for the Python SDK."""
+
+from __future__ import annotations
+
+import httpx
+
+from cortexdb.ingest import IngestAPI
+from cortexdb.query import QueryAPI
+from cortexdb.setup import SetupAPI
+
+
+class CortexDB:
+    """Client for interacting with a CortexDB server.
+
+    Usage::
+
+        from cortexdb import CortexDB
+
+        db = CortexDB("http://localhost:8080")
+
+        # Configure LLM
+        db.setup.configure(
+            provider="GEMINI",
+            api_key="...",
+            chat_model="gemini-2.0-flash",
+            embed_model="gemini-embedding-001",
+        )
+
+        # Ingest content
+        db.ingest.document(uid="user-1", converser="USER", content="Hello world")
+
+        # Query
+        results = db.query.search_contexts("greeting")
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize the CortexDB client.
+
+        Args:
+            base_url: Base URL of the CortexDB server.
+            timeout: Request timeout in seconds.
+            headers: Optional default headers for all requests.
+        """
+        self._http = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers or {},
+        )
+
+        self.setup = SetupAPI(self._http)
+        self.ingest = IngestAPI(self._http)
+        self.query = QueryAPI(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> CortexDB:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"CortexDB(base_url={self._http.base_url!r})"

cortexdb_py-0.1.0/cortexdb/exceptions.py

@@ -0,0 +1,51 @@
+"""Custom exceptions for the CortexDB Python SDK."""
+
+from __future__ import annotations
+
+
+class CortexDBError(Exception):
+    """Base exception for all CortexDB errors."""
+
+    pass
+
+
+class ConnectionError(CortexDBError):
+    """Raised when the SDK cannot connect to the CortexDB server."""
+
+    pass
+
+
+class APIError(CortexDBError):
+    """Raised when the CortexDB server returns an error response."""
+
+    def __init__(self, status_code: int, message: str, detail: str | None = None):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class NotFoundError(APIError):
+    """Raised when a requested resource is not found (404)."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(status_code=404, message=message)
+
+
+class ValidationError(APIError):
+    """Raised when request validation fails (400)."""
+
+    def __init__(self, message: str = "Validation failed", detail: str | None = None):
+        super().__init__(status_code=400, message=message, detail=detail)
+
+
+class LLMError(CortexDBError):
+    """Raised when an LLM operation fails."""
+
+    pass
+
+
+class LLMNotInitializedError(LLMError):
+    """Raised when LLM provider is used before initialization."""
+
+    def __init__(self):
+        super().__init__("LLM provider not initialized. Call initialize() first.")

cortexdb_py-0.1.0/cortexdb/ingest.py

@@ -0,0 +1,54 @@
+"""Ingest API wrapper for CortexDB."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cortexdb.models import ConverserRole, IngestRequest, IngestResponse
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class IngestAPI:
+    """Wraps the ``/api/ingest`` endpoints."""
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def document(
+        self,
+        uid: str,
+        converser: str | ConverserRole,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> IngestResponse:
+        """Ingest a document into CortexDB.
+
+        The server will chunk the content, generate embeddings,
+        and extract entities/relations automatically.
+
+        Args:
+            uid: User identifier.
+            converser: Role of the converser (USER, AGENT, or SYSTEM).
+            content: The text content to ingest.
+            metadata: Optional metadata dict.
+
+        Returns:
+            IngestResponse with the created KnowledgeBase and processing info.
+        """
+        if isinstance(converser, str):
+            converser = ConverserRole(converser.upper())
+
+        request = IngestRequest(
+            uid=uid,
+            converser=converser,
+            content=content,
+            metadata=metadata,
+        )
+        response = self._http.post(
+            "/api/ingest/document",
+            json=request.model_dump(exclude_none=True),
+        )
+        response.raise_for_status()
+        return IngestResponse.model_validate(response.json())

cortexdb_py-0.1.0/cortexdb/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM sub-package for native LLM interactions."""
+
+from cortexdb.llm.provider import LLMProvider
+
+__all__ = ["LLMProvider"]

cortexdb_py-0.1.0/cortexdb/llm/provider.py

@@ -0,0 +1,187 @@
+"""Native LLM provider — Python re-implementation of callLLM() and getEmbedding()."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from cortexdb.exceptions import LLMError, LLMNotInitializedError
+
+logger = logging.getLogger(__name__)
+
+
+class LLMProvider:
+    """LLM provider that directly calls the Gemini / OpenAI APIs from Python.
+
+    This is a native re-implementation of the Java ``LLMProvider`` class,
+    using the ``google-genai`` SDK for Gemini and the ``openai`` SDK for
+    OpenAI/Azure providers.
+
+    Usage::
+
+        from cortexdb.llm import LLMProvider
+
+        llm = LLMProvider(
+            provider="GEMINI",
+            api_key="your-api-key",
+            chat_model="gemini-2.0-flash",
+            embed_model="gemini-embedding-001",
+        )
+
+        embedding = llm.get_embedding("Hello world")
+        response = llm.call_llm("Explain quantum computing")
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        api_key: str,
+        chat_model: str | None = None,
+        embed_model: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        """Initialize the LLM provider.
+
+        Args:
+            provider: Provider name — "GEMINI", "OPENAI", or "AZURE".
+            api_key: API key for authentication.
+            chat_model: Name of the chat model.
+            embed_model: Name of the embedding model.
+            base_url: Custom base URL (optional, mainly for Azure).
+        """
+        self.provider = provider.upper()
+        self.api_key = api_key
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self.base_url = base_url
+
+        self._chat_client: Any = None
+        self._embed_client: Any = None
+
+        self._initialize()
+
+    def _initialize(self) -> None:
+        """Set up the underlying SDK clients based on the provider."""
+        logger.info(
+            "Initializing LLMProvider with provider=%s, chat_model=%s, embed_model=%s",
+            self.provider,
+            self.chat_model,
+            self.embed_model,
+        )
+
+        if self.provider == "GEMINI":
+            self._init_gemini()
+        elif self.provider in ("OPENAI", "AZURE"):
+            self._init_openai()
+        else:
+            raise ValueError(f"Unsupported provider: {self.provider}")
+
+    def _init_gemini(self) -> None:
+        """Initialize using the google-genai SDK."""
+        try:
+            from google import genai
+
+            self._gemini_client = genai.Client(api_key=self.api_key)
+            self._chat_client = self._gemini_client
+            self._embed_client = self._gemini_client
+            logger.info("Gemini client initialized successfully")
+        except ImportError:
+            raise LLMError(
+                "google-genai is required for Gemini provider. "
+                "Install it with: pip install google-genai"
+            )
+
+    def _init_openai(self) -> None:
+        """Initialize using the openai SDK (works for OpenAI and Azure)."""
+        try:
+            import openai
+
+            if self.provider == "AZURE":
+                self._openai_client = openai.AzureOpenAI(
+                    api_key=self.api_key,
+                    azure_endpoint=self.base_url or "",
+                    api_version="2024-02-01",
+                )
+            else:
+                self._openai_client = openai.OpenAI(
+                    api_key=self.api_key,
+                    base_url=self.base_url,
+                )
+            self._chat_client = self._openai_client
+            self._embed_client = self._openai_client
+            logger.info("OpenAI client initialized successfully")
+        except ImportError:
+            raise LLMError(
+                "openai is required for OpenAI/Azure provider. "
+                "Install it with: pip install openai"
+            )
+
+    def get_embedding(self, text: str) -> list[float]:
+        """Generate an embedding vector for the given text.
+
+        Args:
+            text: Input text to embed.
+
+        Returns:
+            A list of floats representing the embedding vector.
+
+        Raises:
+            LLMNotInitializedError: If the provider is not initialized.
+            LLMError: If embedding generation fails.
+        """
+        if self._embed_client is None:
+            raise LLMNotInitializedError()
+
+        logger.debug("Generating embedding for text (%d chars)", len(text))
+
+        try:
+            if self.provider == "GEMINI":
+                response = self._gemini_client.models.embed_content(
+                    model=self.embed_model or "gemini-embedding-001",
+                    contents=text,
+                )
+                return list(response.embeddings[0].values)
+            else:
+                response = self._openai_client.embeddings.create(
+                    model=self.embed_model or "text-embedding-ada-002",
+                    input=text,
+                )
+                return response.data[0].embedding
+        except Exception as e:
+            logger.error("Embedding generation failed: %s", e)
+            raise LLMError(f"Embedding generation failed: {e}") from e
+
+    def call_llm(self, prompt: str) -> str:
+        """Send a prompt to the LLM and return the response text.
+
+        Args:
+            prompt: The prompt to send.
+
+        Returns:
+            The LLM's text response.
+
+        Raises:
+            LLMNotInitializedError: If the provider is not initialized.
+            LLMError: If the LLM call fails.
+        """
+        if self._chat_client is None:
+            raise LLMNotInitializedError()
+
+        logger.debug("Calling LLM with prompt (%d chars)", len(prompt))
+
+        try:
+            if self.provider == "GEMINI":
+                response = self._gemini_client.models.generate_content(
+                    model=self.chat_model or "gemini-2.0-flash",
+                    contents=prompt,
+                )
+                return response.text
+            else:
+                response = self._openai_client.chat.completions.create(
+                    model=self.chat_model or "gpt-4",
+                    messages=[{"role": "user", "content": prompt}],
+                )
+                return response.choices[0].message.content
+        except Exception as e:
+            logger.error("LLM call failed: %s", e)
+            raise LLMError(f"LLM call failed: {e}") from e

cortexdb_py-0.1.0/cortexdb/models.py

@@ -0,0 +1,145 @@
+"""Pydantic data models mirroring the Java DTOs."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+# ─── Enums ───────────────────────────────────────────────────────────
+
+
+class LLMApiProvider(str, Enum):
+    OPENAI = "OPENAI"
+    AZURE = "AZURE"
+    OLLAMA = "OLLAMA"
+    ANTHROPIC = "ANTHROPIC"
+    GEMINI = "GEMINI"
+    MISTRAL = "MISTRAL"
+
+
+class ConverserRole(str, Enum):
+    USER = "USER" #represents content from a human user.
+    AGENT = "AGENT"# represents content generated by the AI aasistant.
+    SYSTEM = "SYSTEM"
+
+
+# ─── Setup ───────────────────────────────────────────────────────────
+
+
+class SetupRequest(BaseModel):
+    provider: LLMApiProvider
+    api_key: str | None = Field(default=None, alias="apiKey")
+    chat_model_name: str = Field(alias="chatModelName")
+    embed_model_name: str = Field(alias="embedModelName")
+    base_url: str | None = Field(default=None, alias="baseUrl")
+
+    model_config = {"populate_by_name": True}
+
+
+class SetupResponse(BaseModel):
+    message: str
+    success: bool
+    configured_provider: str | None = Field(default=None, alias="configuredProvider")
+    configured_chat_model: str | None = Field(
+        default=None, alias="configuredChatModel"
+    )
+    configured_embed_model: str | None = Field(
+        default=None, alias="configuredEmbedModel"
+    )
+    base_url: str | None = Field(default=None, alias="baseUrl")
+    timestamp: datetime | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+# ─── Ingest ──────────────────────────────────────────────────────────
+
+
+class IngestRequest(BaseModel):
+    uid: str
+    converser: ConverserRole
+    content: str
+    metadata: dict[str, Any] | None = None
+
+
+class KnowledgeBase(BaseModel):
+    """Simplified KnowledgeBase entity returned in ingest responses."""
+
+    id: UUID | None = None
+    uid: str | None = None
+    content: str | None = None
+    created_at: datetime | None = Field(default=None, alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class IngestResponse(BaseModel):
+    knowledge_base: KnowledgeBase | None = Field(
+        default=None, alias="knowledgeBase"
+    )
+    status: str | None = None
+    message: str | None = None
+    processing_time_ms: int | None = Field(default=None, alias="processingTimeMs")
+    embedding_time_ms: int | None = Field(default=None, alias="embeddingTimeMs")
+
+    model_config = {"populate_by_name": True}
+
+
+# ─── Query ───────────────────────────────────────────────────────────
+
+
+class QueryRequest(BaseModel):
+    query: str
+    limit: int = 5
+    min_relevance: float = Field(default=0.7, alias="minRelevance")
+    filters: dict[str, Any] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class SearchResult(BaseModel):
+    id: UUID | None = None
+    content: str | None = None
+    score: float | None = None
+    type: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class QueryResponse(BaseModel):
+    query: str | None = None
+    results: list[SearchResult] = Field(default_factory=list)
+    processing_time_ms: int | None = Field(default=None, alias="processingTimeMs")
+
+    model_config = {"populate_by_name": True}
+
+
+# ─── Entity / Relation ───────────────────────────────────────────────
+
+
+class Entity(BaseModel):
+    """RagEntity returned from entity endpoints."""
+
+    id: UUID | None = None
+    name: str | None = None
+    type: str | None = None
+    description: str | None = None
+    embedding: list[float] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class Relation(BaseModel):
+    """Relation between two entities."""
+
+    id: UUID | None = None
+    source_entity_id: UUID | None = Field(default=None, alias="sourceEntityId")
+    target_entity_id: UUID | None = Field(default=None, alias="targetEntityId")
+    relation_type: str | None = Field(default=None, alias="relationType")
+    weight: float | None = None
+
+    model_config = {"populate_by_name": True}

cortexdb_py-0.1.0/cortexdb/query.py

@@ -0,0 +1,262 @@
+"""Query API wrapper for CortexDB."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from cortexdb.exceptions import NotFoundError
+from cortexdb.models import Entity, QueryRequest, QueryResponse, Relation
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class QueryAPI:
+    """Wraps the ``/api/query`` endpoints."""
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    # ── Context endpoints ────────────────────────────────────────────
+
+    def search_contexts(
+        self,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+        filters: dict[str, Any] | None = None,
+    ) -> QueryResponse:
+        """Semantic search on contexts.
+
+        Args:
+            query: Search query text.
+            limit: Maximum number of results.
+            min_relevance: Minimum relevance score (0-1).
+            filters: Optional filters dict.
+
+        Returns:
+            QueryResponse with matching contexts.
+        """
+        return self._post_query("/api/query/contexts", query, limit, min_relevance, filters)
+
+    def get_contexts_by_kb(self, kb_id: UUID | str) -> QueryResponse:
+        """Get all contexts for a knowledge base."""
+        resp = self._http.get(f"/api/query/contexts/kb/{kb_id}")
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def get_recent_contexts(self, days: int = 7) -> QueryResponse:
+        """Get recent contexts from the last N days."""
+        resp = self._http.get("/api/query/contexts/recent", params={"days": days})
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def search_recent_contexts(
+        self,
+        query: str,
+        days: int = 7,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+    ) -> QueryResponse:
+        """Search recent contexts with vector similarity."""
+        return self._post_query(
+            "/api/query/contexts/recent/search",
+            query, limit, min_relevance,
+            params={"days": days},
+        )
+
+    def get_sibling_contexts(self, context_id: UUID | str) -> QueryResponse:
+        """Get sibling contexts (other chunks from same document)."""
+        resp = self._http.get(f"/api/query/contexts/{context_id}/siblings")
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    # ── Entity endpoints ─────────────────────────────────────────────
+
+    def search_entities(
+        self,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+    ) -> QueryResponse:
+        """Semantic search on entities."""
+        return self._post_query("/api/query/entities", query, limit, min_relevance)
+
+    def get_entity_by_name(self, name: str) -> Entity | None:
+        """Find entity by exact name. Returns None if not found."""
+        resp = self._http.get(f"/api/query/entities/name/{name}")
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        return Entity.model_validate(resp.json())
+
+    def get_entity_by_name_ignore_case(self, name: str) -> Entity | None:
+        """Find entity by name (case-insensitive). Returns None if not found."""
+        resp = self._http.get(f"/api/query/entities/name/{name}/ignorecase")
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        return Entity.model_validate(resp.json())
+
+    def get_entity_id_by_name(self, name: str) -> UUID | None:
+        """Get entity ID by name. Returns None if not found."""
+        resp = self._http.get(f"/api/query/entities/id/{name}")
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        data = resp.json()
+        return UUID(str(data.get("id")))
+
+    def disambiguate_entity(self, entity_name: str, context_text: str) -> Entity | None:
+        """Disambiguate entity using vector similarity with context."""
+        resp = self._http.post(
+            "/api/query/entities/disambiguate",
+            params={"entityName": entity_name},
+            content=context_text,
+            headers={"Content-Type": "text/plain"},
+        )
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        return Entity.model_validate(resp.json())
+
+    def get_contexts_for_entity(self, entity_id: UUID | str) -> list[Any]:
+        """Get all contexts where an entity is mentioned."""
+        resp = self._http.get(f"/api/query/entities/{entity_id}/contexts")
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_entities_for_context(self, context_id: UUID | str) -> list[Entity]:
+        """Get all entities mentioned in a context."""
+        resp = self._http.get(f"/api/query/contexts/{context_id}/entities")
+        resp.raise_for_status()
+        return [Entity.model_validate(e) for e in resp.json()]
+
+    def merge_entities(self, source_entity_id: UUID | str, target_entity_id: UUID | str) -> None:
+        """Merge two entities (source into target)."""
+        resp = self._http.post(
+            "/api/query/entities/merge",
+            params={
+                "sourceEntityId": str(source_entity_id),
+                "targetEntityId": str(target_entity_id),
+            },
+        )
+        resp.raise_for_status()
+
+    # ── History endpoints ────────────────────────────────────────────
+
+    def search_history(
+        self,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+    ) -> QueryResponse:
+        """Semantic search on knowledge bases (history)."""
+        return self._post_query("/api/query/history", query, limit, min_relevance)
+
+    def get_history_by_user(self, uid: str) -> QueryResponse:
+        """Get all history for a user."""
+        resp = self._http.get(f"/api/query/history/user/{uid}")
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def get_recent_kbs(self, hours: int = 24) -> QueryResponse:
+        """Get recent knowledge bases from the last N hours."""
+        resp = self._http.get("/api/query/history/recent", params={"hours": hours})
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def get_kbs_since(self, since: str) -> QueryResponse:
+        """Get knowledge bases since a timestamp (ISO-8601)."""
+        resp = self._http.get("/api/query/history/since", params={"since": since})
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    # ── User data ────────────────────────────────────────────────────
+
+    def delete_user_data(self, uid: str) -> None:
+        """Delete all data for a user (GDPR compliance)."""
+        resp = self._http.delete(f"/api/query/user/{uid}")
+        resp.raise_for_status()
+
+    # ── Graph endpoints ──────────────────────────────────────────────
+
+    def get_outgoing_connections(self, entity_id: UUID | str) -> QueryResponse:
+        """Get outgoing relations for an entity."""
+        resp = self._http.get(f"/api/query/graph/outgoing/{entity_id}")
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def get_incoming_connections(self, entity_id: UUID | str) -> QueryResponse:
+        """Get incoming relations for an entity."""
+        resp = self._http.get(f"/api/query/graph/incoming/{entity_id}")
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())
+
+    def get_two_hop_connections(self, entity_id: UUID | str) -> list[str]:
+        """Get 2-hop connections (entity names reachable in 2 hops)."""
+        resp = self._http.get(f"/api/query/graph/two-hop/{entity_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_top_relations(self, limit: int = 10) -> list[Relation]:
+        """Get top/strongest relations."""
+        resp = self._http.get("/api/query/graph/top-relations", params={"limit": limit})
+        resp.raise_for_status()
+        return [Relation.model_validate(r) for r in resp.json()]
+
+    def get_relations_by_source(self, source_id: UUID | str) -> list[Relation]:
+        """Get relations by source entity."""
+        resp = self._http.get(f"/api/query/graph/relations/source/{source_id}")
+        resp.raise_for_status()
+        return [Relation.model_validate(r) for r in resp.json()]
+
+    def get_relations_by_target(self, target_id: UUID | str) -> list[Relation]:
+        """Get relations by target entity."""
+        resp = self._http.get(f"/api/query/graph/relations/target/{target_id}")
+        resp.raise_for_status()
+        return [Relation.model_validate(r) for r in resp.json()]
+
+    def get_relations_by_type(self, relation_type: str) -> list[Relation]:
+        """Get relations by type."""
+        resp = self._http.get(f"/api/query/graph/relations/type/{relation_type}")
+        resp.raise_for_status()
+        return [Relation.model_validate(r) for r in resp.json()]
+
+    # ── Hybrid search ────────────────────────────────────────────────
+
+    def hybrid_search(
+        self,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+    ) -> QueryResponse:
+        """Hybrid search combining vector and graph results."""
+        return self._post_query("/api/query/hybrid", query, limit, min_relevance)
+
+    # ── Internal helpers ─────────────────────────────────────────────
+
+    def _post_query(
+        self,
+        url: str,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+        filters: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> QueryResponse:
+        """Send a POST query request and parse the response."""
+        request = QueryRequest(
+            query=query,
+            limit=limit,
+            minRelevance=min_relevance,
+            filters=filters,
+        )
+        resp = self._http.post(
+            url,
+            json=request.model_dump(by_alias=True, exclude_none=True),
+            params=params,
+        )
+        resp.raise_for_status()
+        return QueryResponse.model_validate(resp.json())

cortexdb_py-0.1.0/cortexdb/setup.py

@@ -0,0 +1,54 @@
+"""Setup API wrapper for CortexDB."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cortexdb.models import LLMApiProvider, SetupRequest, SetupResponse
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class SetupAPI:
+    """Wraps the ``/api/setup`` endpoint."""
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def configure(
+        self,
+        provider: str | LLMApiProvider,
+        chat_model: str,
+        embed_model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> SetupResponse:
+        """Configure the LLM provider on the CortexDB server.
+
+        Args:
+            provider: LLM provider name (e.g. "GEMINI", "OPENAI", "AZURE").
+            chat_model: Name of the chat model.
+            embed_model: Name of the embedding model.
+            api_key: API key for the provider.
+            base_url: Custom base URL (optional).
+
+        Returns:
+            SetupResponse with configuration details.
+        """
+        if isinstance(provider, str):
+            provider = LLMApiProvider(provider.upper())
+
+        request = SetupRequest(
+            provider=provider,
+            apiKey=api_key,
+            chatModelName=chat_model,
+            embedModelName=embed_model,
+            baseUrl=base_url,
+        )
+        response = self._http.post(
+            "/api/setup",
+            json=request.model_dump(by_alias=True, exclude_none=True),
+        )
+        response.raise_for_status()
+        return SetupResponse.model_validate(response.json())

cortexdb_py-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "cortexdb-py"
+version = "0.1.0"
+description = "Python SDK for CortexDB — a RAG-powered memory database"
+authors = ["VectorNode"]
+readme = "README.md"
+packages = [{include = "cortexdb"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+httpx = "^0.28.0"
+pydantic = "^2.0"
+google-genai = "^1.0.0"
+python-dotenv = "^1.0.0"
+eval-type-backport = "^0.3.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.25.0"
+respx = "^0.22.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]