@totaland/create-starter-kit 2.0.3 → 2.0.5

package/templates/python-backend/src/features/agents/router.py

@@ -0,0 +1,164 @@
+"""Agent workflow endpoints with LangGraph orchestration."""
+
+import uuid
+import json
+from typing import AsyncIterator
+
+from fastapi import APIRouter, HTTPException
+from sse_starlette.sse import EventSourceResponse
+from langchain_core.messages import HumanMessage
+
+from src.lib.llm import get_llm
+from src.lib.agents import AgentBuilder, get_default_tools, AgentConfig
+from src.lib.logging import get_logger
+from src.config import get_settings
+from .schemas import AgentRequest, AgentResponse, AgentStep, AgentStreamEvent
+
+router = APIRouter(prefix="/agents", tags=["Agents"])
+logger = get_logger(__name__)
+settings = get_settings()
+
+DEFAULT_SYSTEM_PROMPT = """You are a helpful AI assistant with access to tools.
+
+When you need to take an action or get information, use the available tools.
+Think step by step and explain your reasoning.
+Always provide a clear, helpful final answer.
+"""
+
+
+@router.post("/invoke", response_model=AgentResponse)
+async def invoke_agent(request: AgentRequest):
+    """
+    Invoke an AI agent to process a message.
+    
+    The agent will:
+    1. Analyze the request
+    2. Use tools if needed
+    3. Reason through the problem
+    4. Return a final answer
+    
+    Supports streaming for real-time step updates.
+    """
+    try:
+        provider = request.provider or settings.default_llm_provider
+        thread_id = request.thread_id or str(uuid.uuid4())
+        
+        llm = get_llm(
+            provider=provider,
+            model=request.model,
+            streaming=request.stream,
+        )
+        
+        tools = get_default_tools()
+        
+        agent = (
+            AgentBuilder(name="assistant")
+            .with_llm(llm)
+            .with_tools(tools)
+            .with_system_prompt(request.system_prompt or DEFAULT_SYSTEM_PROMPT)
+            .with_memory()
+            .with_config(AgentConfig(max_iterations=request.max_iterations))
+            .build()
+        )
+        
+        if request.stream:
+            return EventSourceResponse(
+                stream_agent_execution(agent, request.message, thread_id, provider, request.model),
+                media_type="text/event-stream"
+            )
+        
+        result = await agent.ainvoke(
+            {"messages": [HumanMessage(content=request.message)]},
+            config={"configurable": {"thread_id": thread_id}}
+        )
+        
+        messages = result.get("messages", [])
+        final_message = messages[-1] if messages else None
+        
+        return AgentResponse(
+            answer=str(final_message.content) if final_message else "No response generated",
+            steps=[],
+            thread_id=thread_id,
+            model=request.model or (settings.openai_model if provider == "openai" else settings.anthropic_model),
+            provider=provider,
+        )
+        
+    except Exception as e:
+        logger.error("Agent invocation failed", error=str(e))
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def stream_agent_execution(
+    agent, 
+    message: str, 
+    thread_id: str,
+    provider: str,
+    model: str | None
+) -> AsyncIterator[dict]:
+    """Stream agent execution events."""
+    try:
+        config = {"configurable": {"thread_id": thread_id}}
+        
+        async for event in agent.astream_events(
+            {"messages": [HumanMessage(content=message)]},
+            config=config,
+            version="v2"
+        ):
+            kind = event["event"]
+            
+            if kind == "on_chat_model_stream":
+                chunk = event["data"]["chunk"]
+                if chunk.content:
+                    yield {
+                        "event": "token",
+                        "data": json.dumps({"content": chunk.content})
+                    }
+                    
+            elif kind == "on_tool_start":
+                yield {
+                    "event": "tool_start",
+                    "data": json.dumps({
+                        "tool": event["name"],
+                        "input": event["data"].get("input", {})
+                    })
+                }
+                
+            elif kind == "on_tool_end":
+                yield {
+                    "event": "tool_end",
+                    "data": json.dumps({
+                        "tool": event["name"],
+                        "output": str(event["data"].get("output", ""))
+                    })
+                }
+        
+        yield {
+            "event": "done",
+            "data": json.dumps({
+                "thread_id": thread_id,
+                "model": model or settings.openai_model,
+                "provider": provider
+            })
+        }
+        
+    except Exception as e:
+        logger.error("Agent streaming error", error=str(e))
+        yield {
+            "event": "error",
+            "data": json.dumps({"error": str(e)})
+        }
+
+
+@router.get("/tools")
+async def list_available_tools():
+    """List all available tools for agents."""
+    tools = get_default_tools()
+    return {
+        "tools": [
+            {
+                "name": tool.name,
+                "description": tool.description,
+            }
+            for tool in tools
+        ]
+    }

package/templates/python-backend/src/features/agents/schemas.py

@@ -0,0 +1,52 @@
+"""Agent workflow schemas."""
+
+from pydantic import BaseModel, Field
+from typing import Literal, Any
+
+
+class AgentMessage(BaseModel):
+    """A message in the agent conversation."""
+    role: Literal["user", "assistant", "tool"] = Field(description="Message role")
+    content: str = Field(description="Message content")
+    tool_calls: list[dict] | None = Field(default=None, description="Tool calls made")
+    tool_call_id: str | None = Field(default=None, description="ID of tool call this responds to")
+
+
+class AgentRequest(BaseModel):
+    """Request to invoke an agent."""
+    message: str = Field(description="User message to process")
+    thread_id: str | None = Field(default=None, description="Thread ID for conversation memory")
+    provider: Literal["openai", "anthropic"] | None = Field(default=None)
+    model: str | None = Field(default=None)
+    system_prompt: str | None = Field(default=None, description="Override system prompt")
+    tools: list[str] | None = Field(
+        default=None, 
+        description="Tool names to enable (default: all)"
+    )
+    max_iterations: int = Field(default=10, ge=1, le=50, description="Max reasoning steps")
+    stream: bool = Field(default=True, description="Stream intermediate steps")
+
+
+class AgentStep(BaseModel):
+    """A single step in agent execution."""
+    step_type: Literal["thought", "tool_call", "tool_result", "final_answer"]
+    content: str
+    tool_name: str | None = None
+    tool_input: dict | None = None
+    tool_output: str | None = None
+
+
+class AgentResponse(BaseModel):
+    """Complete agent response."""
+    answer: str = Field(description="Final answer from the agent")
+    steps: list[AgentStep] = Field(default_factory=list, description="Execution steps")
+    thread_id: str | None = Field(description="Thread ID for follow-up")
+    tokens_used: int | None = None
+    model: str
+    provider: str
+
+
+class AgentStreamEvent(BaseModel):
+    """Streaming event from agent execution."""
+    event: Literal["step", "tool_start", "tool_end", "token", "done", "error"]
+    data: dict[str, Any]

package/templates/python-backend/src/features/chat/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/templates/python-backend/src/features/chat/router.py

@@ -0,0 +1,98 @@
+"""Chat completion endpoints with streaming support."""
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from sse_starlette.sse import EventSourceResponse
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+import json
+
+from src.lib.llm import get_llm, stream_llm_response, count_message_tokens
+from src.lib.logging import get_logger
+from src.config import get_settings
+from .schemas import ChatRequest, ChatResponse, ChatMessage
+
+router = APIRouter(prefix="/chat", tags=["Chat"])
+logger = get_logger(__name__)
+settings = get_settings()
+
+
+def convert_to_langchain_messages(messages: list[ChatMessage]):
+    """Convert API messages to LangChain format."""
+    result = []
+    for msg in messages:
+        if msg.role == "user":
+            result.append(HumanMessage(content=msg.content))
+        elif msg.role == "assistant":
+            result.append(AIMessage(content=msg.content))
+        elif msg.role == "system":
+            result.append(SystemMessage(content=msg.content))
+    return result
+
+
+@router.post("/completions", response_model=ChatResponse)
+async def create_chat_completion(request: ChatRequest) -> ChatResponse | StreamingResponse:
+    """
+    Create a chat completion.
+    
+    Supports both streaming (SSE) and non-streaming responses.
+    """
+    try:
+        provider = request.provider or settings.default_llm_provider
+        messages = convert_to_langchain_messages(request.messages)
+        
+        if request.stream:
+            return EventSourceResponse(
+                stream_chat_response(messages, provider, request.model),
+                media_type="text/event-stream"
+            )
+        
+        llm = get_llm(
+            provider=provider,
+            model=request.model,
+            temperature=request.temperature,
+            max_tokens=request.max_tokens,
+            streaming=False,
+        )
+        
+        response = await llm.ainvoke(messages)
+        
+        return ChatResponse(
+            message=ChatMessage(role="assistant", content=str(response.content)),
+            usage={
+                "prompt_tokens": count_message_tokens(messages),
+                "completion_tokens": count_message_tokens([response]),
+                "total_tokens": count_message_tokens(messages + [response]),
+            },
+            model=request.model or (settings.openai_model if provider == "openai" else settings.anthropic_model),
+            provider=provider,
+        )
+    except Exception as e:
+        logger.error("Chat completion failed", error=str(e))
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def stream_chat_response(messages, provider: str, model: str | None):
+    """Generate SSE events for streaming chat response."""
+    try:
+        async for chunk in stream_llm_response(messages, provider=provider, model=model):
+            yield {
+                "event": "message",
+                "data": json.dumps({"delta": chunk})
+            }
+        yield {
+            "event": "done",
+            "data": json.dumps({"finish_reason": "stop"})
+        }
+    except Exception as e:
+        logger.error("Streaming error", error=str(e))
+        yield {
+            "event": "error",
+            "data": json.dumps({"error": str(e)})
+        }
+
+
+@router.post("/completions/sync", response_model=ChatResponse)
+async def create_chat_completion_sync(request: ChatRequest) -> ChatResponse:
+    """Create a non-streaming chat completion."""
+    request.stream = False
+    return await create_chat_completion(request)

package/templates/python-backend/src/features/chat/schemas.py

@@ -0,0 +1,36 @@
+"""Chat feature schemas."""
+
+from pydantic import BaseModel, Field
+from typing import Literal
+
+
+class ChatMessage(BaseModel):
+    """A single chat message."""
+    role: Literal["user", "assistant", "system"] = Field(description="Message role")
+    content: str = Field(description="Message content")
+
+
+class ChatRequest(BaseModel):
+    """Request for chat completion."""
+    messages: list[ChatMessage] = Field(description="Conversation messages")
+    provider: Literal["openai", "anthropic"] | None = Field(
+        default=None, description="LLM provider to use"
+    )
+    model: str | None = Field(default=None, description="Model override")
+    temperature: float | None = Field(default=None, ge=0, le=2, description="Temperature")
+    max_tokens: int | None = Field(default=None, ge=1, description="Max tokens")
+    stream: bool = Field(default=True, description="Enable streaming response")
+
+
+class ChatResponse(BaseModel):
+    """Non-streaming chat response."""
+    message: ChatMessage
+    usage: dict[str, int] | None = None
+    model: str
+    provider: str
+
+
+class ChatStreamChunk(BaseModel):
+    """A streaming response chunk."""
+    delta: str
+    finish_reason: str | None = None

package/templates/python-backend/src/features/health/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/templates/python-backend/src/features/health/router.py

@@ -0,0 +1,13 @@
+from fastapi import APIRouter
+from .schemas import HealthResponse
+import pendulum
+
+router = APIRouter(prefix="/health", tags=["Health"])
+
+
+@router.get("", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    return HealthResponse(
+        status="healthy",
+        timestamp=pendulum.now("UTC").to_iso8601_string(),
+    )

package/templates/python-backend/src/features/health/schemas.py

@@ -0,0 +1,6 @@
+import msgspec
+
+
+class HealthResponse(msgspec.Struct):
+    status: str
+    timestamp: str

package/templates/python-backend/src/features/orders/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/templates/python-backend/src/features/orders/router.py

@@ -0,0 +1,40 @@
+from fastapi import APIRouter, HTTPException
+from uuid import uuid4
+from .schemas import Order, CreateOrderRequest, OrderListResponse
+from src.lib.cache import cached
+
+router = APIRouter(prefix="/orders", tags=["Orders"])
+
+_orders: dict[str, Order] = {}
+
+
+@router.get("", response_model=OrderListResponse)
+@cached(ttl=60)
+async def list_orders() -> OrderListResponse:
+    return OrderListResponse(orders=list(_orders.values()))
+
+
+@router.get("/{order_id}", response_model=Order)
+async def get_order(order_id: str) -> Order:
+    if order_id not in _orders:
+        raise HTTPException(status_code=404, detail="Order not found")
+    return _orders[order_id]
+
+
+@router.post("", response_model=Order, status_code=201)
+async def create_order(request: CreateOrderRequest) -> Order:
+    order = Order(
+        id=str(uuid4()),
+        product=request.product,
+        quantity=request.quantity,
+        price=request.price,
+    )
+    _orders[order.id] = order
+    return order
+
+
+@router.delete("/{order_id}", status_code=204)
+async def delete_order(order_id: str) -> None:
+    if order_id not in _orders:
+        raise HTTPException(status_code=404, detail="Order not found")
+    del _orders[order_id]

package/templates/python-backend/src/features/orders/schemas.py

@@ -0,0 +1,18 @@
+import msgspec
+
+
+class Order(msgspec.Struct):
+    id: str
+    product: str
+    quantity: int
+    price: float
+
+
+class CreateOrderRequest(msgspec.Struct):
+    product: str
+    quantity: int
+    price: float
+
+
+class OrderListResponse(msgspec.Struct):
+    orders: list[Order]

package/templates/python-backend/src/lib/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-backend/src/lib/agents.py

@@ -0,0 +1,167 @@
+"""
+LangGraph Agent utilities and base components.
+
+Provides:
+- AgentState: Base state class for LangGraph workflows
+- Tool registration and execution helpers
+- Graph building utilities
+- Common agent patterns (ReAct, Plan-and-Execute)
+"""
+
+from typing import Annotated, Sequence, TypedDict, Any, Callable
+from dataclasses import dataclass, field
+import operator
+import json
+
+from langchain_core.messages import BaseMessage, HumanMessage, AIMessage, ToolMessage
+from langchain_core.tools import BaseTool, tool
+from langgraph.graph import StateGraph, END
+from langgraph.prebuilt import ToolNode
+from langgraph.checkpoint.memory import MemorySaver
+
+from src.lib.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentState(TypedDict):
+    """Base state for LangGraph agents."""
+    messages: Annotated[Sequence[BaseMessage], operator.add]
+    next_action: str | None
+    intermediate_steps: list[tuple[str, str]]
+    metadata: dict[str, Any]
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for agent behavior."""
+    max_iterations: int = 10
+    return_intermediate_steps: bool = False
+    handle_parsing_errors: bool = True
+    verbose: bool = False
+
+
+def create_tool_node(tools: list[BaseTool]) -> ToolNode:
+    """Create a LangGraph ToolNode from a list of tools."""
+    return ToolNode(tools)
+
+
+def should_continue(state: AgentState) -> str:
+    """Determine if the agent should continue or end."""
+    messages = state["messages"]
+    last_message = messages[-1]
+    
+    if hasattr(last_message, "tool_calls") and last_message.tool_calls:
+        return "tools"
+    return END
+
+
+def format_tool_result(tool_name: str, result: Any) -> str:
+    """Format tool execution result for the agent."""
+    if isinstance(result, dict):
+        return json.dumps(result, indent=2)
+    return str(result)
+
+
+class AgentBuilder:
+    """Builder pattern for creating LangGraph agents."""
+    
+    def __init__(self, name: str = "agent"):
+        self.name = name
+        self.tools: list[BaseTool] = []
+        self.llm = None
+        self.system_prompt: str = ""
+        self.checkpointer = None
+        self.config = AgentConfig()
+    
+    def with_llm(self, llm) -> "AgentBuilder":
+        """Set the LLM for the agent."""
+        self.llm = llm
+        return self
+    
+    def with_tools(self, tools: list[BaseTool]) -> "AgentBuilder":
+        """Add tools to the agent."""
+        self.tools.extend(tools)
+        return self
+    
+    def with_system_prompt(self, prompt: str) -> "AgentBuilder":
+        """Set the system prompt."""
+        self.system_prompt = prompt
+        return self
+    
+    def with_memory(self) -> "AgentBuilder":
+        """Enable memory/checkpointing."""
+        self.checkpointer = MemorySaver()
+        return self
+    
+    def with_config(self, config: AgentConfig) -> "AgentBuilder":
+        """Set agent configuration."""
+        self.config = config
+        return self
+    
+    def build(self) -> StateGraph:
+        """Build and return the agent graph."""
+        if not self.llm:
+            raise ValueError("LLM must be set before building")
+        
+        llm_with_tools = self.llm.bind_tools(self.tools) if self.tools else self.llm
+        
+        def agent_node(state: AgentState) -> dict:
+            """The main agent reasoning node."""
+            messages = list(state["messages"])
+            
+            if self.system_prompt and not any(
+                isinstance(m, HumanMessage) and "system" in str(m.content).lower() 
+                for m in messages[:1]
+            ):
+                from langchain_core.messages import SystemMessage
+                messages = [SystemMessage(content=self.system_prompt)] + messages
+            
+            response = llm_with_tools.invoke(messages)
+            return {"messages": [response]}
+        
+        graph = StateGraph(AgentState)
+        graph.add_node("agent", agent_node)
+        
+        if self.tools:
+            tool_node = create_tool_node(self.tools)
+            graph.add_node("tools", tool_node)
+            graph.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
+            graph.add_edge("tools", "agent")
+        else:
+            graph.add_edge("agent", END)
+        
+        graph.set_entry_point("agent")
+        
+        return graph.compile(checkpointer=self.checkpointer)
+
+
+@tool
+def search_web(query: str) -> str:
+    """Search the web for information. Use this when you need current information."""
+    return f"[Mock search result for: {query}] - Replace with actual implementation"
+
+
+@tool
+def get_current_time() -> str:
+    """Get the current date and time."""
+    import pendulum
+    return pendulum.now("UTC").to_iso8601_string()
+
+
+@tool
+def calculate(expression: str) -> str:
+    """Evaluate a mathematical expression. Example: calculate('2 + 2')"""
+    try:
+        allowed_chars = set("0123456789+-*/.() ")
+        if not all(c in allowed_chars for c in expression):
+            return "Error: Invalid characters in expression"
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def get_default_tools() -> list[BaseTool]:
+    """Get the default set of tools for agents."""
+    return [search_web, get_current_time, calculate]

package/templates/python-backend/src/lib/cache.py

@@ -0,0 +1,38 @@
+from cachetools import TTLCache
+from functools import wraps
+from typing import TypeVar, Callable, Any
+import asyncio
+
+T = TypeVar("T")
+
+_cache: TTLCache[str, Any] = TTLCache(maxsize=1000, ttl=300)
+
+
+def cached(ttl: int = 300, maxsize: int = 128) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Simple in-memory cache decorator with TTL support."""
+    cache: TTLCache[str, Any] = TTLCache(maxsize=maxsize, ttl=ttl)
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            key = f"{func.__name__}:{args}:{kwargs}"
+            if key in cache:
+                return cache[key]
+            result = await func(*args, **kwargs)
+            cache[key] = result
+            return result
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            key = f"{func.__name__}:{args}:{kwargs}"
+            if key in cache:
+                return cache[key]
+            result = func(*args, **kwargs)
+            cache[key] = result
+            return result
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+
+    return decorator

package/templates/python-backend/src/lib/database.py

@@ -0,0 +1,31 @@
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from src.config import get_settings
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+settings = get_settings()
+engine = create_async_engine(settings.database_url, echo=settings.debug)
+async_session_maker = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def init_db() -> None:
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+@asynccontextmanager
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise