touchdb-ai 2.0.2__tar.gz

touchdb_ai-2.0.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: touchdb-ai
+Version: 2.0.2
+Summary: TouchDB AI - Generate SQL queries and perform data analytics using autonomous agents
+Author-email: TouchDB AI Team <contact@touchdb.ai>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pandas
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: PyYAML
+Requires-Dist: plotly
+Requires-Dist: tabulate
+Requires-Dist: sqlparse
+Requires-Dist: sqlalchemy
+Requires-Dist: requests
+Requires-Dist: anthropic ; extra == "anthropic"
+Requires-Dist: google-cloud-bigquery ; extra == "bigquery"
+Requires-Dist: clickhouse_connect ; extra == "clickhouse"
+Requires-Dist: duckdb ; extra == "duckdb"
+Requires-Dist: fastapi>=0.68.0 ; extra == "fastapi"
+Requires-Dist: uvicorn>=0.15.0 ; extra == "fastapi"
+Requires-Dist: flask>=2.0.0 ; extra == "flask"
+Requires-Dist: flask-cors>=4.0.0 ; extra == "flask"
+Requires-Dist: google-genai ; extra == "gemini"
+Requires-Dist: google-generativeai ; extra == "google"
+Requires-Dist: google-cloud-aiplatform ; extra == "google"
+Requires-Dist: PyMySQL ; extra == "mysql"
+Requires-Dist: ollama ; extra == "ollama"
+Requires-Dist: httpx ; extra == "ollama"
+Requires-Dist: openai ; extra == "openai"
+Requires-Dist: psycopg2-binary ; extra == "postgres"
+Requires-Dist: db-dtypes ; extra == "postgres"
+Requires-Dist: touchdb-ai[flask, fastapi] ; extra == "servers"
+Requires-Dist: snowflake-connector-python ; extra == "snowflake"
+Project-URL: Bug Tracker, https://github.com/touchdb-ai/touchdb/issues
+Project-URL: Homepage, https://github.com/touchdb-ai/touchdb
+Provides-Extra: anthropic
+Provides-Extra: bigquery
+Provides-Extra: clickhouse
+Provides-Extra: duckdb
+Provides-Extra: fastapi
+Provides-Extra: flask
+Provides-Extra: gemini
+Provides-Extra: google
+Provides-Extra: mysql
+Provides-Extra: ollama
+Provides-Extra: openai
+Provides-Extra: postgres
+Provides-Extra: servers
+Provides-Extra: snowflake
+Provides-Extra: sqlite
+
+# TouchDB AI 🚀
+
+**TouchDB AI** is an open-source, user-aware Agentic framework for autonomous Text-to-SQL generation, data analysis, and conversational database intelligence.
+
+---
+
+## Key Highlights
+
+- **User-Aware Security & Multi-Tenancy**: Granular permissions, request-context user resolution, and role-based tool execution.
+- **Pluggable Database Runners**: Native support for SQLite, DuckDB, PostgreSQL, MySQL, Snowflake, BigQuery, ClickHouse, and more.
+- **Multi-LLM Support**: Seamless integrations with Google Gemini, OpenAI, Anthropic Claude, Ollama (local models), and custom LLM providers.
+- **Adaptive Tool Memory**: Stores successful execution patterns in memory, getting smarter with each interaction.
+- **Pre-built Web Server & CLI**: Built-in interactive CLI and FastAPI / Flask server components.
+
+---
+
+## Quick Installation
+
+```bash
+pip install -e .
+```
+
+Or install with database / LLM extras:
+```bash
+pip install -e ".[fastapi,openai,gemini]"
+```
+
+---
+
+## Quickstart Example
+
+```python
+import asyncio
+from touchdb import Agent, AgentConfig, ToolRegistry, User
+from touchdb.core.user.resolver import UserResolver
+from touchdb.core.user.request_context import RequestContext
+from touchdb.integrations.local.agent_memory.in_memory import DemoAgentMemory
+from touchdb.integrations.sqlite import SqliteRunner
+from touchdb.tools import RunSqlTool
+from touchdb.integrations.mock import MockLlmService
+
+# 1. Setup Database Runner & Tool
+runner = SqliteRunner(database_path="ecommerce.db")
+sql_tool = RunSqlTool(sql_runner=runner)
+
+registry = ToolRegistry()
+registry.register_local_tool(sql_tool, access_groups=["default"])
+
+# 2. Define User Resolver
+class SimpleUserResolver(UserResolver):
+    async def resolve_user(self, ctx: RequestContext) -> User:
+        return User(id="user_1", username="admin", group_memberships=["default"])
+
+# 3. Create TouchDB Agent
+agent = Agent(
+    llm_service=MockLlmService(response_content="Querying database..."),
+    tool_registry=registry,
+    user_resolver=SimpleUserResolver(),
+    agent_memory=DemoAgentMemory(),
+    config=AgentConfig(stream_responses=False)
+)
+
+# 4. Ask questions
+async def ask(question: str):
+    async for component in agent.send_message(
+        request_context=RequestContext(),
+        message=question,
+        conversation_id="conv_1"
+    ):
+        if component.rich_component and hasattr(component.rich_component, "content"):
+            print(component.rich_component.content)
+
+asyncio.run(ask("Show top 5 sales"))
+```
+
+---
+
+## Interactive CLI & Web Server
+
+TouchDB AI includes an interactive CLI and web server:
+
+```bash
+# Start TouchDB Server with FastAPI
+touchdb --framework fastapi --port 8000 --example mock_custom_tool
+
+# List available examples
+touchdb --list-examples
+```
+
+---
+
+## License
+
+MIT License.
+

touchdb_ai-2.0.2/README.md

@@ -0,0 +1,94 @@
+# TouchDB AI 🚀
+
+**TouchDB AI** is an open-source, user-aware Agentic framework for autonomous Text-to-SQL generation, data analysis, and conversational database intelligence.
+
+---
+
+## Key Highlights
+
+- **User-Aware Security & Multi-Tenancy**: Granular permissions, request-context user resolution, and role-based tool execution.
+- **Pluggable Database Runners**: Native support for SQLite, DuckDB, PostgreSQL, MySQL, Snowflake, BigQuery, ClickHouse, and more.
+- **Multi-LLM Support**: Seamless integrations with Google Gemini, OpenAI, Anthropic Claude, Ollama (local models), and custom LLM providers.
+- **Adaptive Tool Memory**: Stores successful execution patterns in memory, getting smarter with each interaction.
+- **Pre-built Web Server & CLI**: Built-in interactive CLI and FastAPI / Flask server components.
+
+---
+
+## Quick Installation
+
+```bash
+pip install -e .
+```
+
+Or install with database / LLM extras:
+```bash
+pip install -e ".[fastapi,openai,gemini]"
+```
+
+---
+
+## Quickstart Example
+
+```python
+import asyncio
+from touchdb import Agent, AgentConfig, ToolRegistry, User
+from touchdb.core.user.resolver import UserResolver
+from touchdb.core.user.request_context import RequestContext
+from touchdb.integrations.local.agent_memory.in_memory import DemoAgentMemory
+from touchdb.integrations.sqlite import SqliteRunner
+from touchdb.tools import RunSqlTool
+from touchdb.integrations.mock import MockLlmService
+
+# 1. Setup Database Runner & Tool
+runner = SqliteRunner(database_path="ecommerce.db")
+sql_tool = RunSqlTool(sql_runner=runner)
+
+registry = ToolRegistry()
+registry.register_local_tool(sql_tool, access_groups=["default"])
+
+# 2. Define User Resolver
+class SimpleUserResolver(UserResolver):
+    async def resolve_user(self, ctx: RequestContext) -> User:
+        return User(id="user_1", username="admin", group_memberships=["default"])
+
+# 3. Create TouchDB Agent
+agent = Agent(
+    llm_service=MockLlmService(response_content="Querying database..."),
+    tool_registry=registry,
+    user_resolver=SimpleUserResolver(),
+    agent_memory=DemoAgentMemory(),
+    config=AgentConfig(stream_responses=False)
+)
+
+# 4. Ask questions
+async def ask(question: str):
+    async for component in agent.send_message(
+        request_context=RequestContext(),
+        message=question,
+        conversation_id="conv_1"
+    ):
+        if component.rich_component and hasattr(component.rich_component, "content"):
+            print(component.rich_component.content)
+
+asyncio.run(ask("Show top 5 sales"))
+```
+
+---
+
+## Interactive CLI & Web Server
+
+TouchDB AI includes an interactive CLI and web server:
+
+```bash
+# Start TouchDB Server with FastAPI
+touchdb --framework fastapi --port 8000 --example mock_custom_tool
+
+# List available examples
+touchdb --list-examples
+```
+
+---
+
+## License
+
+MIT License.

touchdb_ai-2.0.2/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "touchdb-ai"
+version = "2.0.2"
+authors = [
+  { name="TouchDB AI Team", email="contact@touchdb.ai" },
+]
+description = "TouchDB AI - Generate SQL queries and perform data analytics using autonomous agents"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "click>=8.0.0",
+    "pandas",
+    "httpx>=0.28.0",
+    "PyYAML",
+    "plotly",
+    "tabulate",
+    "sqlparse",
+    "sqlalchemy",
+    "requests",
+]
+
+[project.scripts]
+touchdb = "touchdb.servers.cli.server_runner:main"
+
+[project.urls]
+"Homepage" = "https://github.com/touchdb-ai/touchdb"
+"Bug Tracker" = "https://github.com/touchdb-ai/touchdb/issues"
+
+[project.optional-dependencies]
+flask = ["flask>=2.0.0", "flask-cors>=4.0.0"]
+fastapi = ["fastapi>=0.68.0", "uvicorn>=0.15.0"]
+servers = ["touchdb-ai[flask,fastapi]"]
+postgres = ["psycopg2-binary", "db-dtypes"]
+mysql = ["PyMySQL"]
+clickhouse = ["clickhouse_connect"]
+bigquery = ["google-cloud-bigquery"]
+snowflake = ["snowflake-connector-python"]
+duckdb = ["duckdb"]
+google = ["google-generativeai", "google-cloud-aiplatform"]
+openai = ["openai"]
+anthropic = ["anthropic"]
+gemini = ["google-genai"]
+ollama = ["ollama", "httpx"]
+sqlite = []
+
+[tool.flit.module]
+name = "touchdb"
+path = "src/touchdb"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

touchdb_ai-2.0.2/src/touchdb/__init__.py

@@ -0,0 +1,172 @@
+"""
+TouchDB Agents - A modular framework for building LLM agents.
+
+This package provides a flexible framework for creating conversational AI agents
+with tool execution, conversation management, and user scoping.
+"""
+
+# Version information
+__version__ = "2.0.2"
+
+# Import core framework components
+from .core import (
+    # Interfaces
+    Agent,
+    ConversationStore,
+    LlmService,
+    SystemPromptBuilder,
+    Tool,
+    UserService,
+    T,
+    # Models
+    Conversation,
+    LlmMessage,
+    LlmRequest,
+    LlmResponse,
+    LlmStreamChunk,
+    Message,
+    ToolCall,
+    ToolContext,
+    ToolResult,
+    ToolSchema,
+    User,
+    # UI Components
+    UiComponent,
+    SimpleComponent,
+    SimpleComponentType,
+    SimpleTextComponent,
+    SimpleImageComponent,
+    SimpleLinkComponent,
+    # Rich Components
+    ArtifactComponent,
+    BadgeComponent,
+    CardComponent,
+    DataFrameComponent,
+    IconTextComponent,
+    LogViewerComponent,
+    NotificationComponent,
+    ProgressBarComponent,
+    ProgressDisplayComponent,
+    RichTextComponent,
+    StatusCardComponent,
+    TaskListComponent,
+    # Core implementations
+    Agent,
+    AgentConfig,
+    DefaultSystemPromptBuilder,
+    DefaultWorkflowHandler,
+    ToolRegistry,
+    # Evaluation
+    Evaluator,
+    TestCase,
+    ExpectedOutcome,
+    AgentResult,
+    EvaluationResult,
+    TestCaseResult,
+    AgentVariant,
+    EvaluationRunner,
+    TrajectoryEvaluator,
+    OutputEvaluator,
+    LLMAsJudgeEvaluator,
+    EfficiencyEvaluator,
+    EvaluationReport,
+    ComparisonReport,
+    EvaluationDataset,
+    # Exceptions
+    AgentError,
+    ConversationNotFoundError,
+    LlmServiceError,
+    PermissionError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ValidationError,
+)
+
+# Import basic implementations
+from .integrations import MemoryConversationStore, MockLlmService
+
+# Main exports
+__all__ = [
+    # Version
+    "__version__",
+    # Core interfaces
+    "Agent",
+    "Tool",
+    "LlmService",
+    "ConversationStore",
+    "UserService",
+    "SystemPromptBuilder",
+    "T",
+    # Models
+    "User",
+    "Message",
+    "Conversation",
+    "ToolCall",
+    "ToolResult",
+    "ToolContext",
+    "ToolSchema",
+    "LlmMessage",
+    "LlmRequest",
+    "LlmResponse",
+    "LlmStreamChunk",
+    # UI Components
+    "UiComponent",
+    "SimpleComponent",
+    "SimpleComponentType",
+    "SimpleTextComponent",
+    "SimpleImageComponent",
+    "SimpleLinkComponent",
+    # Rich Components
+    "ArtifactComponent",
+    "BadgeComponent",
+    "CardComponent",
+    "DataFrameComponent",
+    "IconTextComponent",
+    "LogViewerComponent",
+    "NotificationComponent",
+    "ProgressBarComponent",
+    "ProgressDisplayComponent",
+    "RichTextComponent",
+    "StatusCardComponent",
+    "TaskListComponent",
+    # Core implementations
+    "Agent",
+    "AgentConfig",
+    "ToolRegistry",
+    "DefaultSystemPromptBuilder",
+    "DefaultWorkflowHandler",
+    # Evaluation
+    "Evaluator",
+    "TestCase",
+    "ExpectedOutcome",
+    "AgentResult",
+    "EvaluationResult",
+    "TestCaseResult",
+    "AgentVariant",
+    "EvaluationRunner",
+    "TrajectoryEvaluator",
+    "OutputEvaluator",
+    "LLMAsJudgeEvaluator",
+    "EfficiencyEvaluator",
+    "EvaluationReport",
+    "ComparisonReport",
+    "EvaluationDataset",
+    # Basic implementations
+    "MemoryConversationStore",
+    "MockLlmService",
+    # Server components
+    "TouchDBFlaskServer",
+    "TouchDBFastAPIServer",
+    "ChatHandler",
+    "ChatRequest",
+    "ChatStreamChunk",
+    "ExampleAgentLoader",
+    # Exceptions
+    "AgentError",
+    "ToolExecutionError",
+    "ToolNotFoundError",
+    "PermissionError",
+    "ConversationNotFoundError",
+    "LlmServiceError",
+    "ValidationError",
+]

touchdb_ai-2.0.2/src/touchdb/agents/__init__.py

@@ -0,0 +1,7 @@
+"""
+Agent implementations.
+
+This package contains agent implementations and utilities.
+"""
+
+__all__: list[str] = []

touchdb_ai-2.0.2/src/touchdb/capabilities/__init__.py

@@ -0,0 +1,17 @@
+"""
+Capabilities module.
+
+This package contains abstractions for tool capabilities - reusable utilities
+that tools can compose via dependency injection.
+"""
+
+from .file_system import CommandResult, FileSearchMatch, FileSystem
+from .sql_runner import RunSqlToolArgs, SqlRunner
+
+__all__ = [
+    "FileSystem",
+    "FileSearchMatch",
+    "CommandResult",
+    "SqlRunner",
+    "RunSqlToolArgs",
+]

touchdb_ai-2.0.2/src/touchdb/capabilities/agent_memory/__init__.py

@@ -0,0 +1,21 @@
+"""
+Agent memory capability package.
+"""
+
+from .base import AgentMemory
+from .models import (
+    MemoryStats,
+    TextMemory,
+    TextMemorySearchResult,
+    ToolMemory,
+    ToolMemorySearchResult,
+)
+
+__all__ = [
+    "AgentMemory",
+    "TextMemory",
+    "TextMemorySearchResult",
+    "ToolMemory",
+    "ToolMemorySearchResult",
+    "MemoryStats",
+]

touchdb_ai-2.0.2/src/touchdb/capabilities/agent_memory/base.py

@@ -0,0 +1,103 @@
+"""
+Agent memory capability interface for tool usage learning.
+
+This module contains the abstract base class for agent memory operations,
+following the same pattern as the FileSystem interface.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from touchdb.core.tool import ToolContext
+    from .models import (
+        ToolMemorySearchResult,
+        TextMemory,
+        TextMemorySearchResult,
+        ToolMemory,
+    )
+
+
+class AgentMemory(ABC):
+    """Abstract base class for agent memory operations."""
+
+    @abstractmethod
+    async def save_tool_usage(
+        self,
+        question: str,
+        tool_name: str,
+        args: Dict[str, Any],
+        context: "ToolContext",
+        success: bool = True,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Save a tool usage pattern for future reference."""
+        pass
+
+    @abstractmethod
+    async def save_text_memory(
+        self, content: str, context: "ToolContext"
+    ) -> "TextMemory":
+        """Save a free-form text memory."""
+        pass
+
+    @abstractmethod
+    async def search_similar_usage(
+        self,
+        question: str,
+        context: "ToolContext",
+        *,
+        limit: int = 10,
+        similarity_threshold: float = 0.7,
+        tool_name_filter: Optional[str] = None,
+    ) -> List[ToolMemorySearchResult]:
+        """Search for similar tool usage patterns based on a question."""
+        pass
+
+    @abstractmethod
+    async def search_text_memories(
+        self,
+        query: str,
+        context: "ToolContext",
+        *,
+        limit: int = 10,
+        similarity_threshold: float = 0.7,
+    ) -> List["TextMemorySearchResult"]:
+        """Search stored text memories based on a query."""
+        pass
+
+    @abstractmethod
+    async def get_recent_memories(
+        self, context: "ToolContext", limit: int = 10
+    ) -> List[ToolMemory]:
+        """Get recently added memories. Returns most recent memories first."""
+        pass
+
+    @abstractmethod
+    async def get_recent_text_memories(
+        self, context: "ToolContext", limit: int = 10
+    ) -> List["TextMemory"]:
+        """Fetch recently stored text memories."""
+        pass
+
+    @abstractmethod
+    async def delete_by_id(self, context: "ToolContext", memory_id: str) -> bool:
+        """Delete a memory by its ID. Returns True if deleted, False if not found."""
+        pass
+
+    @abstractmethod
+    async def delete_text_memory(self, context: "ToolContext", memory_id: str) -> bool:
+        """Delete a text memory by its ID. Returns True if deleted, False if not found."""
+        pass
+
+    @abstractmethod
+    async def clear_memories(
+        self,
+        context: "ToolContext",
+        tool_name: Optional[str] = None,
+        before_date: Optional[str] = None,
+    ) -> int:
+        """Clear stored memories (tool or text). Returns number of memories deleted."""
+        pass

touchdb_ai-2.0.2/src/touchdb/capabilities/agent_memory/models.py

@@ -0,0 +1,53 @@
+"""
+Memory storage models and types.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel
+
+
+class ToolMemory(BaseModel):
+    """Represents a stored tool usage memory."""
+
+    memory_id: Optional[str] = None
+    question: str
+    tool_name: str
+    args: Dict[str, Any]
+    timestamp: Optional[str] = None
+    success: bool = True
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class TextMemory(BaseModel):
+    """Represents a stored free-form text memory."""
+
+    memory_id: Optional[str] = None
+    content: str
+    timestamp: Optional[str] = None
+
+
+class ToolMemorySearchResult(BaseModel):
+    """Represents a search result from tool memory storage."""
+
+    memory: ToolMemory
+    similarity_score: float
+    rank: int
+
+
+class TextMemorySearchResult(BaseModel):
+    """Represents a search result from text memory storage."""
+
+    memory: TextMemory
+    similarity_score: float
+    rank: int
+
+
+class MemoryStats(BaseModel):
+    """Memory storage statistics."""
+
+    total_memories: int
+    unique_tools: int
+    unique_questions: int
+    success_rate: float
+    most_used_tools: Dict[str, int]

touchdb_ai-2.0.2/src/touchdb/capabilities/file_system/__init__.py

@@ -0,0 +1,14 @@
+"""
+File system capability.
+
+This module provides abstractions for file system operations used by tools.
+"""
+
+from .base import FileSystem
+from .models import CommandResult, FileSearchMatch
+
+__all__ = [
+    "FileSystem",
+    "FileSearchMatch",
+    "CommandResult",
+]