redis-agent-kit 0.1.0__py3-none-any.whl

redis_agent_kit/__init__.py

@@ -0,0 +1,222 @@
+"""Redis Agent Kit - Reusable infrastructure for building AI agents with Redis."""
+
+__version__ = "0.1.0"
+
+# Core (AgentKit handles background processing internally)
+# Pipelines (import submodule for namespaced access)
+# Tools
+from redis_agent_kit import pipelines, tools
+
+# Agent and Knowledge
+from redis_agent_kit.agent import Agent, AgentConfig
+
+# API Auth (optional – requires the [api] extra for FastAPI)
+try:
+    from redis_agent_kit.api.auth import (
+        create_api_key_dependency,
+        create_optional_api_key_dependency,
+    )
+except ImportError:  # pragma: no cover - exercised only without [api]
+    create_api_key_dependency = None  # type: ignore[assignment]
+    create_optional_api_key_dependency = None  # type: ignore[assignment]
+
+# Attachments
+from redis_agent_kit.attachments import (
+    AttachmentStore,
+    InlineAttachmentStore,
+    RedisAttachmentStore,
+    get_attachment_data,
+)
+
+# Config
+from redis_agent_kit.config import (
+    MemorySettings,
+    ModelSettings,
+    Settings,
+    SideEffectSettings,
+    TaskSettings,
+    get_settings,
+    reset_settings,
+    set_settings,
+)
+from redis_agent_kit.core import (
+    AgentCallable,
+    AgentKit,
+    ConcurrencyConfig,
+    ContextAgentCallable,
+    RetryConfig,
+    create_task_with_session,
+)
+
+# Emitter
+from redis_agent_kit.emitter import TaskEmitter
+
+# Keys
+from redis_agent_kit.keys import RedisKeys
+from redis_agent_kit.knowledge import KnowledgeStore
+
+# Memory
+from redis_agent_kit.memory import Memory, MemorySearchResults, MessageList, NoOpMemory
+
+# Task Middleware
+# Pipeline Middleware
+from redis_agent_kit.middleware import (
+    EmitterMiddleware,
+    MemoryMiddleware,
+    MiddlewareChain,
+    PipelineContext,
+    PipelineLoggingMiddleware,
+    PipelineMiddleware,
+    PipelineMiddlewareChain,
+    PipelineTimingMiddleware,
+    PipelineValidationMiddleware,
+    RAGMiddleware,
+    ResultMiddleware,
+    TaskContext,
+    TaskMiddleware,
+)
+
+# Models
+from redis_agent_kit.models import (
+    AgentCard,
+    AgentManifest,
+    AgentMetadata,
+    AgentStatus,
+    Attachment,
+    AttachmentType,
+    Caller,
+    CallerType,
+    Capability,
+    InputRequest,
+    Message,
+    Skill,
+    TaskState,
+    TaskStatus,
+    TaskUpdate,
+)
+
+# Side Effects (reentrant tasks)
+from redis_agent_kit.side_effects import (
+    DEFAULT_KEY_POLICY,
+    FUNCTION_NAME,
+    FUNCTION_SOURCE,
+    INPUTS,
+    clear_side_effects,
+    side_effect,
+)
+
+# Streaming
+from redis_agent_kit.streaming import ChannelScope, StreamConfig
+
+# Managers
+from redis_agent_kit.task_manager import TaskManager
+from redis_agent_kit.thread_manager import ThreadManager
+from redis_agent_kit.tools import (
+    Tool,
+    ToolCapability,
+    ToolDefinition,
+    ToolManager,
+    ToolMetadata,
+    ToolProvider,
+)
+
+# Vectorizer
+from redis_agent_kit.vectorizer import LiteLLMVectorizerAdapter, Vectorizer
+
+__all__ = [
+    # Core
+    "AgentKit",
+    "AgentCallable",
+    "ContextAgentCallable",
+    "create_task_with_session",
+    # Task configuration helpers
+    "RetryConfig",
+    "ConcurrencyConfig",
+    # Config
+    "Settings",
+    "MemorySettings",
+    "TaskSettings",
+    "ModelSettings",
+    "SideEffectSettings",
+    "get_settings",
+    "set_settings",
+    "reset_settings",
+    # Side Effects (reentrant tasks)
+    "side_effect",
+    "clear_side_effects",
+    "FUNCTION_SOURCE",
+    "FUNCTION_NAME",
+    "INPUTS",
+    "DEFAULT_KEY_POLICY",
+    # Memory
+    "Memory",
+    "MessageList",
+    "MemorySearchResults",
+    "NoOpMemory",
+    # Managers
+    "TaskManager",
+    "ThreadManager",
+    # Emitter
+    "TaskEmitter",
+    # Task Middleware
+    "TaskMiddleware",
+    "TaskContext",
+    "MiddlewareChain",
+    "EmitterMiddleware",
+    "RAGMiddleware",
+    "MemoryMiddleware",
+    "ResultMiddleware",
+    # Pipeline Middleware
+    "PipelineMiddleware",
+    "PipelineContext",
+    "PipelineMiddlewareChain",
+    "PipelineLoggingMiddleware",
+    "PipelineTimingMiddleware",
+    "PipelineValidationMiddleware",
+    # Models
+    "AgentCard",
+    "AgentManifest",
+    "AgentMetadata",
+    "AgentStatus",
+    "Attachment",
+    "AttachmentType",
+    "Caller",
+    "CallerType",
+    "Capability",
+    "InputRequest",
+    "Message",
+    "Skill",
+    "TaskState",
+    "TaskStatus",
+    # Attachment Storage
+    "AttachmentStore",
+    "RedisAttachmentStore",
+    "InlineAttachmentStore",
+    "get_attachment_data",
+    "TaskUpdate",
+    # Keys
+    "RedisKeys",
+    # API Auth
+    "create_api_key_dependency",
+    "create_optional_api_key_dependency",
+    # Pipelines submodule
+    "pipelines",
+    # Agent and Knowledge
+    "Agent",
+    "AgentConfig",
+    "KnowledgeStore",
+    # Vectorizer
+    "Vectorizer",
+    "LiteLLMVectorizerAdapter",
+    # Tools
+    "tools",
+    "Tool",
+    "ToolCapability",
+    "ToolDefinition",
+    "ToolManager",
+    "ToolMetadata",
+    "ToolProvider",
+    # Streaming
+    "StreamConfig",
+    "ChannelScope",
+]

redis_agent_kit/agent.py

@@ -0,0 +1,265 @@
+"""Framework-agnostic Agent base class using LiteLLM."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import litellm
+import redis.asyncio as redis
+
+from redis_agent_kit.knowledge import KnowledgeStore
+from redis_agent_kit.tools import ToolManager, ToolProvider
+from redis_agent_kit.tools.knowledge_provider import KnowledgeProvider
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Message:
+    """A message in the conversation."""
+
+    role: str  # "system", "user", "assistant", "tool"
+    content: str | None = None
+    tool_calls: list[Any] | None = None
+    tool_call_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for LiteLLM."""
+        d: dict[str, Any] = {"role": self.role}
+        if self.content is not None:
+            d["content"] = self.content
+        if self.tool_calls:
+            d["tool_calls"] = self.tool_calls
+        if self.tool_call_id:
+            d["tool_call_id"] = self.tool_call_id
+        return d
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for Agent."""
+
+    model: str = "gpt-4o-mini"
+    system_prompt: str | None = None
+    temperature: float = 0.7
+    max_tokens: int | None = None
+    max_tool_iterations: int = 10
+    use_knowledge: bool = True
+    use_tools: bool = True
+    knowledge_context_limit: int = 5
+
+
+class Agent:
+    """Framework-agnostic agent with LiteLLM backend.
+
+    Example:
+        agent = Agent(
+            model="gpt-4o-mini",  # Or "anthropic/claude-3-5-sonnet"
+            redis_url="redis://localhost:6379",
+        )
+
+        # Ingest knowledge
+        await agent.knowledge.ingest("Redis uses RDB for persistence...")
+
+        # Add custom tools
+        agent.tools.add_provider(MyProvider())
+
+        # Chat
+        response = await agent.chat("How does Redis persistence work?")
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        system_prompt: str | None = None,
+        redis_url: str = "redis://localhost:6379",
+        redis_client: redis.Redis | None = None,
+        config: AgentConfig | None = None,
+    ):
+        """Initialize agent.
+
+        Args:
+            model: LiteLLM model name (e.g., "gpt-4o-mini", "anthropic/claude-3-5-sonnet").
+            system_prompt: Optional system prompt.
+            redis_url: Redis connection URL.
+            redis_client: Optional existing Redis client.
+            config: Optional full configuration.
+        """
+        self._config = config or AgentConfig(model=model, system_prompt=system_prompt)
+        self._client = redis_client or redis.from_url(redis_url, decode_responses=True)  # type: ignore[no-untyped-call]
+
+        # Core components
+        self.knowledge = KnowledgeStore(self._client)
+        self.tools = ToolManager()
+
+        # Register built-in knowledge tool
+        self._knowledge_provider = KnowledgeProvider(self.knowledge)
+        self.tools.add_provider(self._knowledge_provider)
+
+        # Conversation history
+        self._history: list[Message] = []
+
+    @property
+    def model(self) -> str:
+        """Get the model name."""
+        return self._config.model
+
+    @property
+    def config(self) -> AgentConfig:
+        """Get agent configuration."""
+        return self._config
+
+    def add_provider(self, provider: ToolProvider) -> None:
+        """Add a tool provider.
+
+        Args:
+            provider: ToolProvider instance.
+        """
+        self.tools.add_provider(provider)
+
+    def clear_history(self) -> None:
+        """Clear conversation history."""
+        self._history.clear()
+
+    async def chat(
+        self,
+        message: str,
+        use_knowledge: bool | None = None,
+        use_tools: bool | None = None,
+    ) -> str:
+        """Send a message and get a response.
+
+        Args:
+            message: User message.
+            use_knowledge: Override config to enable/disable knowledge context.
+            use_tools: Override config to enable/disable tools.
+
+        Returns:
+            Assistant response.
+        """
+        use_knowledge = use_knowledge if use_knowledge is not None else self._config.use_knowledge
+        use_tools = use_tools if use_tools is not None else self._config.use_tools
+
+        messages = self._build_messages(message, use_knowledge=use_knowledge)
+
+        # Get tools
+        tools = None
+        if use_tools and self.tools._tools:
+            tools = self.tools.get_openai_tools()
+
+        # Call LLM
+        response = await self._call_llm(messages, tools)
+
+        # Handle tool calls
+        iterations = 0
+        while (
+            response.choices[0].message.tool_calls and iterations < self._config.max_tool_iterations
+        ):
+            response = await self._handle_tool_calls(response, messages)
+            iterations += 1
+
+        # Extract response
+        assistant_content = response.choices[0].message.content or ""
+
+        # Store in history
+        self._history.append(Message(role="user", content=message))
+        self._history.append(Message(role="assistant", content=assistant_content))
+
+        return assistant_content
+
+    def _build_messages(
+        self,
+        user_message: str,
+        use_knowledge: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Build message list for LLM call."""
+        messages: list[dict[str, Any]] = []
+
+        # System prompt
+        if self._config.system_prompt:
+            messages.append({"role": "system", "content": self._config.system_prompt})
+
+        # History
+        for msg in self._history:
+            messages.append(msg.to_dict())
+
+        # User message
+        messages.append({"role": "user", "content": user_message})
+
+        return messages
+
+    async def _call_llm(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+    ) -> Any:
+        """Call LLM via LiteLLM."""
+        kwargs: dict[str, Any] = {
+            "model": self._config.model,
+            "messages": messages,
+            "temperature": self._config.temperature,
+        }
+
+        if self._config.max_tokens:
+            kwargs["max_tokens"] = self._config.max_tokens
+
+        if tools:
+            kwargs["tools"] = tools
+
+        return await litellm.acompletion(**kwargs)
+
+    async def _handle_tool_calls(
+        self,
+        response: Any,
+        messages: list[dict[str, Any]],
+    ) -> Any:
+        """Execute tool calls and continue conversation."""
+        assistant_msg = response.choices[0].message
+
+        # Add assistant message with tool calls
+        messages.append(
+            {
+                "role": "assistant",
+                "content": assistant_msg.content,
+                "tool_calls": [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                    }
+                    for tc in assistant_msg.tool_calls
+                ],
+            }
+        )
+
+        # Execute each tool call
+        for tool_call in assistant_msg.tool_calls:
+            tool_name = tool_call.function.name
+            try:
+                args = json.loads(tool_call.function.arguments)
+            except json.JSONDecodeError:
+                args = {}
+
+            try:
+                result = await self.tools.execute(tool_name, args)
+                result_str = json.dumps(result) if not isinstance(result, str) else result
+            except Exception as e:
+                logger.warning(f"Tool {tool_name} failed: {e}")
+                result_str = json.dumps({"error": str(e)})
+
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": result_str,
+                }
+            )
+
+        # Continue conversation with tool results
+        return await self._call_llm(messages, self.tools.get_openai_tools())

redis_agent_kit/api/__init__.py

@@ -0,0 +1,21 @@
+"""Redis Agent Kit REST API.
+
+The REST API requires the ``[api]`` extra (FastAPI + Uvicorn). ``create_app``
+is loaded lazily so that importing :mod:`redis_agent_kit.api` on a bare
+install does not eagerly fail when FastAPI is not installed.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+__all__ = ["create_app"]
+
+if TYPE_CHECKING:  # pragma: no cover
+    from redis_agent_kit.api.app import create_app
+
+
+def __getattr__(name: str) -> Any:
+    if name == "create_app":
+        from redis_agent_kit.api.app import create_app as _create_app
+
+        return _create_app
+    raise AttributeError(f"module 'redis_agent_kit.api' has no attribute {name!r}")

redis_agent_kit/api/app.py

@@ -0,0 +1,163 @@
+"""Redis Agent Kit REST API application."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, FastAPI
+
+from redis_agent_kit import __version__
+from redis_agent_kit.api.auth import create_optional_api_key_dependency
+from redis_agent_kit.api.pipelines import router as pipelines_router
+from redis_agent_kit.api.tasks import router as tasks_router
+from redis_agent_kit.api.v1 import router as v1_router
+from redis_agent_kit.config import get_settings
+from redis_agent_kit.models import AgentCard, AgentManifest
+from redis_agent_kit.protocols.a2a import create_a2a_router
+from redis_agent_kit.protocols.acp import create_acp_router
+from redis_agent_kit.streaming import StreamConfig
+
+
+def create_app(
+    redis_url: str | None = None,
+    prefix: str = "rak",
+    queue_name: str | None = None,
+    enable_a2a: bool = False,
+    enable_acp: bool = False,
+    enable_sse: bool = False,
+    enable_streaming: bool = False,
+    stream_config: StreamConfig | None = None,
+    agent_card: AgentCard | None = None,
+    agent_manifest: AgentManifest | None = None,
+    kit: Any = None,
+    api_keys: list[str] | None = None,
+    **kwargs: Any,
+) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        redis_url: Redis connection URL (defaults to settings).
+        prefix: Redis key prefix.
+        queue_name: Background worker queue name (defaults to settings).
+        enable_a2a: Enable A2A protocol endpoints.
+        enable_acp: Enable ACP protocol endpoints.
+        enable_sse: Enable Server-Sent Events streaming endpoint for tasks.
+            Deprecated – use ``stream_config`` instead.
+        enable_streaming: Enable lightweight Pub/Sub token streaming.
+            Deprecated – use ``stream_config`` instead.
+        stream_config: Structured streaming configuration. When provided,
+            ``enable_sse`` and ``enable_streaming`` are ignored.
+        agent_card: Agent card for A2A discovery (required if enable_a2a=True).
+        agent_manifest: Agent manifest for ACP discovery (required if enable_acp=True).
+        kit: AgentKit instance for protocol handlers (required if protocols enabled).
+        api_keys: Optional list of valid API keys. If provided, all endpoints
+            (except /, /health, /docs) require authentication via X-API-Key
+            header or Authorization: Bearer token.
+        **kwargs: Additional arguments passed to FastAPI constructor.
+            Common options include:
+            - title: API title (default: "Redis Agent Kit API")
+            - description: API description
+            - version: API version (default: package version)
+            - docs_url: URL for Swagger docs (default: "/docs")
+            - redoc_url: URL for ReDoc (default: "/redoc")
+            - openapi_url: URL for OpenAPI schema (default: "/openapi.json")
+            - middleware: List of middleware to add
+            - dependencies: Global dependencies
+            - lifespan: Lifespan context manager
+
+    Returns:
+        Configured FastAPI application.
+
+    Raises:
+        ValueError: If protocol is enabled but required config is missing.
+    """
+    # Validate protocol configuration
+    if enable_a2a and agent_card is None:
+        raise ValueError("agent_card is required when A2A is enabled")
+    if enable_acp and agent_manifest is None:
+        raise ValueError("agent_manifest is required when ACP is enabled")
+    if (enable_a2a or enable_acp) and kit is None:
+        raise ValueError("kit is required when protocols are enabled")
+
+    settings = get_settings()
+    resolved_redis_url = redis_url or settings.redis_url
+    resolved_queue_name = queue_name or settings.task.queue_name
+
+    # Create API key dependency if keys provided
+    auth_dependency = create_optional_api_key_dependency(api_keys)
+
+    # Set defaults that can be overridden by kwargs
+    fastapi_kwargs: dict[str, Any] = {
+        "title": "Redis Agent Kit API",
+        "description": "REST API for managing agent tasks and data pipelines",
+        "version": __version__,
+    }
+    fastapi_kwargs.update(kwargs)
+
+    app = FastAPI(**fastapi_kwargs)
+
+    # Resolve StreamConfig
+    if stream_config is not None:
+        resolved_stream_config = stream_config
+    else:
+        resolved_stream_config = StreamConfig.from_booleans(enable_sse, enable_streaming)
+
+    # Store config in app state
+    app.state.redis_url = resolved_redis_url
+    app.state.prefix = prefix
+    app.state.queue_name = resolved_queue_name
+    app.state.kit = kit
+    app.state.api_keys = api_keys
+    app.state.enable_a2a = enable_a2a
+    app.state.enable_acp = enable_acp
+    app.state.enable_mcp = bool(kwargs.get("enable_mcp", False))
+    app.state.default_agent_id = kwargs.get("default_agent_id", "default")
+    app.state.stream_config = resolved_stream_config
+    app.state.enable_sse = enable_sse
+    app.state.enable_streaming = enable_streaming
+
+    # Register routes (public - no auth required)
+    @app.get("/")
+    async def root() -> dict[str, str]:
+        """Get API information."""
+        return {
+            "name": "Redis Agent Kit API",
+            "version": __version__,
+            "docs": "/docs",
+        }
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        """Health check endpoint."""
+        return {"status": "healthy"}
+
+    # Build dependencies list for protected routers
+    router_dependencies = [Depends(auth_dependency)] if auth_dependency else []
+
+    # Register routers (protected if api_keys provided)
+    app.include_router(
+        tasks_router, prefix="/tasks", tags=["tasks"], dependencies=router_dependencies
+    )
+    app.include_router(
+        pipelines_router,
+        prefix="/pipelines",
+        tags=["pipelines"],
+        dependencies=router_dependencies,
+    )
+    app.include_router(
+        v1_router,
+        tags=["v1"],
+        dependencies=router_dependencies,
+    )
+
+    # Mount A2A router if enabled (protected if api_keys provided)
+    if enable_a2a and agent_card is not None and kit is not None:
+        a2a_router = create_a2a_router(agent_card=agent_card, kit=kit)
+        app.include_router(a2a_router, tags=["A2A"], dependencies=router_dependencies)
+
+    # Mount ACP router if enabled (protected if api_keys provided)
+    if enable_acp and agent_manifest is not None and kit is not None:
+        acp_router = create_acp_router(agent_manifest=agent_manifest, kit=kit)
+        app.include_router(acp_router, tags=["ACP"], dependencies=router_dependencies)
+
+    return app