agent-runtime-core 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

agent_runtime_core/tools.py

@@ -0,0 +1,179 @@
+"""
+Tool utilities for building tool schemas.
+
+This module provides utilities for creating tool schemas that can be passed
+to LLMs for function calling. The ToolSchemaBuilder provides a fluent API
+for building schemas without manually constructing JSON.
+
+Example:
+    from agent_runtime_core.tools import ToolSchemaBuilder
+    
+    # Build a tool schema fluently
+    schema = (
+        ToolSchemaBuilder("get_weather")
+        .description("Get the current weather for a location")
+        .param("location", "string", "City name", required=True)
+        .param("units", "string", "Temperature units", enum=["celsius", "fahrenheit"])
+        .build()
+    )
+    
+    # Convert to OpenAI format for LLM calls
+    openai_format = schema.to_openai_format()
+
+Note: For registering tools with handlers, use Tool and ToolRegistry from
+agent_runtime_core.interfaces. This module is for schema building only.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional, Sequence
+
+
+@dataclass
+class ToolParameter:
+    """
+    Definition of a tool parameter.
+    
+    Attributes:
+        name: Parameter name
+        type: JSON Schema type (string, integer, number, boolean, array, object)
+        description: Human-readable description
+        required: Whether the parameter is required
+        enum: Optional list of allowed values
+        items: For array types, the schema of array items
+        default: Default value if not provided
+    """
+    name: str
+    type: str
+    description: str = ""
+    required: bool = False
+    enum: Optional[list[str]] = None
+    items: Optional[dict[str, Any]] = None
+    default: Optional[Any] = None
+    
+    def to_schema(self) -> dict[str, Any]:
+        """Convert to JSON Schema format."""
+        schema: dict[str, Any] = {"type": self.type}
+        if self.description:
+            schema["description"] = self.description
+        if self.enum:
+            schema["enum"] = self.enum
+        if self.items:
+            schema["items"] = self.items
+        if self.default is not None:
+            schema["default"] = self.default
+        return schema
+
+
+@dataclass
+class ToolSchema:
+    """
+    Complete tool schema in OpenAI function calling format.
+    
+    Example:
+        schema = ToolSchema(
+            name="get_weather",
+            description="Get the current weather for a location",
+            parameters=[
+                ToolParameter("location", "string", "City name", required=True),
+                ToolParameter("units", "string", "Temperature units", enum=["celsius", "fahrenheit"]),
+            ],
+        )
+        
+        # Convert to OpenAI format
+        openai_schema = schema.to_openai_format()
+    """
+    name: str
+    description: str
+    parameters: list[ToolParameter] = field(default_factory=list)
+    
+    def to_openai_format(self) -> dict[str, Any]:
+        """Convert to OpenAI function calling format."""
+        properties = {}
+        required = []
+        
+        for param in self.parameters:
+            properties[param.name] = param.to_schema()
+            if param.required:
+                required.append(param.name)
+        
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            },
+        }
+
+
+class ToolSchemaBuilder:
+    """
+    Builder for creating tool schemas fluently.
+    
+    Example:
+        schema = (
+            ToolSchemaBuilder("submit_order")
+            .description("Submit a customer order")
+            .param("customer_id", "string", "Customer ID", required=True)
+            .param("items", "array", "Order items", items={"type": "string"})
+            .param("priority", "string", "Priority level", enum=["low", "normal", "high"])
+            .build()
+        )
+    """
+    
+    def __init__(self, name: str):
+        """Initialize builder with tool name."""
+        self._name = name
+        self._description = ""
+        self._parameters: list[ToolParameter] = []
+    
+    def description(self, desc: str) -> "ToolSchemaBuilder":
+        """Set the tool description."""
+        self._description = desc
+        return self
+    
+    def param(
+        self,
+        name: str,
+        type: str,
+        description: str = "",
+        required: bool = False,
+        enum: Optional[list[str]] = None,
+        items: Optional[dict[str, Any]] = None,
+        default: Optional[Any] = None,
+    ) -> "ToolSchemaBuilder":
+        """Add a parameter to the tool."""
+        self._parameters.append(
+            ToolParameter(
+                name=name,
+                type=type,
+                description=description,
+                required=required,
+                enum=enum,
+                items=items,
+                default=default,
+            )
+        )
+        return self
+    
+    def build(self) -> ToolSchema:
+        """Build the tool schema."""
+        return ToolSchema(
+            name=self._name,
+            description=self._description,
+            parameters=self._parameters,
+        )
+    
+    def to_openai_format(self) -> dict[str, Any]:
+        """Build and convert to OpenAI format in one step."""
+        return self.build().to_openai_format()
+
+
+def schemas_to_openai_format(schemas: Sequence[ToolSchema]) -> list[dict[str, Any]]:
+    """Convert a sequence of ToolSchema objects to OpenAI format."""
+    return [schema.to_openai_format() for schema in schemas]
+

agent_runtime_core/vectorstore/__init__.py

@@ -0,0 +1,193 @@
+"""
+Vector store module for agent_runtime_core.
+
+Provides pluggable vector storage backends for similarity search:
+- sqlite-vec: Lightweight, local development (requires: pip install sqlite-vec)
+- pgvector: Production PostgreSQL (requires: pip install pgvector psycopg[binary])
+- Vertex AI: Enterprise-scale managed (requires: pip install google-cloud-aiplatform)
+
+Example usage:
+    from agent_runtime_core.vectorstore import (
+        get_vector_store,
+        get_embedding_client,
+        VectorStore,
+        EmbeddingClient,
+    )
+
+    # Get clients
+    vector_store = get_vector_store("sqlite_vec", path="./vectors.db")
+    embeddings = get_embedding_client("openai")
+
+    # Index a document
+    text = "The quick brown fox jumps over the lazy dog"
+    vector = await embeddings.embed(text)
+    await vector_store.add(
+        id="doc-1",
+        vector=vector,
+        content=text,
+        metadata={"source": "example"},
+    )
+
+    # Search
+    query = "fast animal"
+    query_vector = await embeddings.embed(query)
+    results = await vector_store.search(query_vector, limit=5)
+    for r in results:
+        print(f"{r.score:.3f}: {r.content}")
+"""
+
+from typing import Optional
+
+from agent_runtime_core.vectorstore.base import (
+    VectorStore,
+    VectorRecord,
+    VectorSearchResult,
+)
+from agent_runtime_core.vectorstore.embeddings import (
+    EmbeddingClient,
+    OpenAIEmbeddings,
+    VertexAIEmbeddings,
+)
+
+
+def get_vector_store(backend: str = "sqlite_vec", **kwargs) -> VectorStore:
+    """
+    Factory function to get a vector store instance.
+
+    Args:
+        backend: The backend to use. Options:
+            - "sqlite_vec": SQLite with sqlite-vec extension (default)
+            - "pgvector": PostgreSQL with pgvector extension
+            - "vertex": Google Vertex AI Vector Search
+        **kwargs: Backend-specific configuration options
+
+    Returns:
+        A VectorStore instance
+
+    Raises:
+        ValueError: If the backend is unknown
+        ImportError: If required dependencies are not installed
+
+    Examples:
+        # SQLite-vec (local development)
+        store = get_vector_store("sqlite_vec", path="./vectors.db")
+
+        # PGVector (production PostgreSQL)
+        store = get_vector_store("pgvector", connection_string="postgresql://...")
+
+        # Vertex AI (enterprise scale)
+        store = get_vector_store(
+            "vertex",
+            project_id="my-project",
+            location="us-central1",
+            index_endpoint_id="...",
+            deployed_index_id="...",
+        )
+    """
+    if backend == "sqlite_vec":
+        from agent_runtime_core.vectorstore.sqlite_vec import SqliteVecStore
+
+        return SqliteVecStore(**kwargs)
+    elif backend == "pgvector":
+        # Import from django_agent_runtime if available
+        try:
+            from django_agent_runtime.vectorstore import PgVectorStore
+
+            return PgVectorStore(**kwargs)
+        except ImportError:
+            raise ImportError(
+                "PgVectorStore requires django_agent_runtime. "
+                "Install with: pip install django-agent-runtime[pgvector]"
+            )
+    elif backend == "vertex":
+        from agent_runtime_core.vectorstore.vertex import VertexVectorStore
+
+        return VertexVectorStore(**kwargs)
+    else:
+        raise ValueError(
+            f"Unknown vector store backend: {backend}. "
+            f"Available backends: sqlite_vec, pgvector, vertex"
+        )
+
+
+def get_embedding_client(
+    provider: str = "openai",
+    model: Optional[str] = None,
+    **kwargs,
+) -> EmbeddingClient:
+    """
+    Factory function to get an embedding client.
+
+    Args:
+        provider: The provider to use. Options:
+            - "openai": OpenAI embeddings (default)
+            - "vertex": Google Vertex AI embeddings
+        model: Optional model name override
+        **kwargs: Provider-specific configuration options
+
+    Returns:
+        An EmbeddingClient instance
+
+    Raises:
+        ValueError: If the provider is unknown
+        ImportError: If required dependencies are not installed
+
+    Examples:
+        # OpenAI (default model: text-embedding-3-small)
+        client = get_embedding_client("openai")
+
+        # OpenAI with specific model
+        client = get_embedding_client("openai", model="text-embedding-3-large")
+
+        # Vertex AI
+        client = get_embedding_client(
+            "vertex",
+            model="text-embedding-004",
+            project_id="my-project",
+        )
+    """
+    if provider == "openai":
+        if model:
+            kwargs["model"] = model
+        return OpenAIEmbeddings(**kwargs)
+    elif provider == "vertex":
+        if model:
+            kwargs["model"] = model
+        return VertexAIEmbeddings(**kwargs)
+    else:
+        raise ValueError(
+            f"Unknown embedding provider: {provider}. "
+            f"Available providers: openai, vertex"
+        )
+
+
+# Lazy imports for optional backends
+def __getattr__(name: str):
+    """Lazy import for optional backends."""
+    if name == "SqliteVecStore":
+        from agent_runtime_core.vectorstore.sqlite_vec import SqliteVecStore
+
+        return SqliteVecStore
+    elif name == "VertexVectorStore":
+        from agent_runtime_core.vectorstore.vertex import VertexVectorStore
+
+        return VertexVectorStore
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Abstract interfaces
+    "VectorStore",
+    "VectorRecord",
+    "VectorSearchResult",
+    "EmbeddingClient",
+    # Implementations
+    "OpenAIEmbeddings",
+    "VertexAIEmbeddings",
+    "SqliteVecStore",
+    "VertexVectorStore",
+    # Factory functions
+    "get_vector_store",
+    "get_embedding_client",
+]
+

agent_runtime_core/vectorstore/base.py

@@ -0,0 +1,138 @@
+"""
+Abstract base classes for vector storage backends.
+
+These interfaces define the contract that all vector storage backends must implement.
+Implementations can use different backends like sqlite-vec, pgvector, or Vertex AI.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class VectorRecord:
+    """A stored vector with its content and metadata."""
+
+    id: str
+    vector: list[float]
+    content: str
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class VectorSearchResult:
+    """A search result with similarity score."""
+
+    id: str
+    content: str
+    score: float  # Similarity score (higher = more similar)
+    metadata: dict = field(default_factory=dict)
+
+
+class VectorStore(ABC):
+    """
+    Abstract interface for vector storage and similarity search.
+
+    Vector stores handle storing embeddings and performing similarity searches.
+    Different backends can be used depending on scale and deployment requirements:
+    - sqlite-vec: Lightweight, local development
+    - pgvector: Production PostgreSQL deployments
+    - Vertex AI: Enterprise-scale managed infrastructure
+    """
+
+    @abstractmethod
+    async def add(
+        self,
+        id: str,
+        vector: list[float],
+        content: str,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        """
+        Add a vector with its content and metadata.
+
+        Args:
+            id: Unique identifier for the vector
+            vector: The embedding vector
+            content: Original text content
+            metadata: Optional metadata dictionary
+        """
+        ...
+
+    @abstractmethod
+    async def add_batch(
+        self,
+        items: list[tuple[str, list[float], str, Optional[dict]]],
+    ) -> None:
+        """
+        Add multiple vectors efficiently.
+
+        Args:
+            items: List of (id, vector, content, metadata) tuples
+        """
+        ...
+
+    @abstractmethod
+    async def search(
+        self,
+        query_vector: list[float],
+        limit: int = 10,
+        filter: Optional[dict] = None,
+    ) -> list[VectorSearchResult]:
+        """
+        Search for similar vectors.
+
+        Args:
+            query_vector: The query embedding vector
+            limit: Maximum number of results to return
+            filter: Optional metadata filter (equality matching)
+
+        Returns:
+            List of VectorSearchResult ordered by similarity (highest first)
+        """
+        ...
+
+    @abstractmethod
+    async def delete(self, id: str) -> bool:
+        """
+        Delete a vector by ID.
+
+        Args:
+            id: The vector ID to delete
+
+        Returns:
+            True if the vector existed and was deleted
+        """
+        ...
+
+    @abstractmethod
+    async def delete_by_filter(self, filter: dict) -> int:
+        """
+        Delete vectors matching filter.
+
+        Args:
+            filter: Metadata filter for deletion (equality matching)
+
+        Returns:
+            Number of vectors deleted
+        """
+        ...
+
+    @abstractmethod
+    async def get(self, id: str) -> Optional[VectorRecord]:
+        """
+        Get a vector by ID.
+
+        Args:
+            id: The vector ID to retrieve
+
+        Returns:
+            VectorRecord if found, None otherwise
+        """
+        ...
+
+    async def close(self) -> None:
+        """Close connections. Override if needed."""
+        pass
+