feat: initial FastAPI boilerplate setup

Set up Webber - multi-agent AI development system with:

- Domain-based project structure (src/domains/, src/shared/)
- BaseController pattern with lazy router instantiation
- Pydantic Settings configuration with env file support
- Logger decorator with temporal benchmarking and trace IDs
- UserProvider singleton for request-scoped context
- Custom exception hierarchy
- Health endpoints (/, /health)

Dependencies (CVE checked 2026-01-09):
- FastAPI 0.128.0, Starlette 0.50.0, Uvicorn 0.40.0
- Pydantic 2.12.4, PydanticAI 1.40.0
- All packages at latest safe versions

Placeholder domains for future implementation:
- agents/ (explore, plan, task)
- tools/ (file, shell, search)
- auth/ (tatlock integration)

Port: 8086 (per CONTAINERS.md allocation)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/domains/agents/README.md

@@ -0,0 +1,53 @@
+# Agents Domain
+
+This domain contains PydanticAI agent definitions and orchestration.
+
+## Structure
+
+```
+agents/
+├── router.py        # Agent routes (list, run)
+├── controller.py    # Agent orchestration logic
+├── schemas.py       # Request/response models
+│
+├── explore/         # Explore agent - codebase navigation
+│   ├── agent.py     # PydanticAI agent definition
+│   └── prompts.py   # System prompts
+│
+├── plan/            # Plan agent - implementation design
+│   ├── agent.py
+│   └── prompts.py
+│
+└── task/            # Task agent - execution
+    ├── agent.py
+    └── prompts.py
+```
+
+## PydanticAI Pattern
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.ollama import OllamaModel
+from src.shared.config import get_settings
+
+settings = get_settings()
+
+explore_agent = Agent(
+    OllamaModel(settings.ollama_agent_model, base_url=settings.ollama_url),
+    system_prompt='You are a code exploration assistant...',
+)
+
+@explore_agent.tool
+async def search_files(ctx, pattern: str) -> str:
+    """Search for files matching pattern."""
+    # Implementation uses tools from src/domains/tools/
+    pass
+```
+
+## Adding a New Agent
+
+1. Create a new directory under `agents/` (e.g., `agents/review/`)
+2. Create `agent.py` with PydanticAI Agent definition
+3. Create `prompts.py` with system prompts
+4. Register in `controller.py`
+5. Add tests in `tests/domains/test_agents/`

src/domains/auth/README.md

@@ -0,0 +1,43 @@
+# Auth Domain
+
+This domain handles API key management and authentication.
+
+## Structure
+
+```
+auth/
+├── router.py        # Auth routes
+├── controller.py    # Auth logic
+└── schemas.py       # Auth models
+```
+
+## Authentication Flow
+
+1. Client sends `X-API-Key` header
+2. Middleware validates key (via `shared/auth.py`)
+3. User context set in `shared/context.py`
+4. Routes use `Depends(require_auth)` for protected endpoints
+
+## Integration with Tatlock
+
+API keys are validated against the tatlock-ui/core-api user management system.
+
+```python
+# In shared/auth.py
+async def validate_api_key(api_key: str) -> Optional[User]:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{settings.tatlock_api_url}/auth/validate",
+            headers={"X-API-Key": api_key}
+        )
+        if response.status_code == 200:
+            return User(**response.json())
+    return None
+```
+
+## TODO
+
+- [ ] Implement tatlock API key validation
+- [ ] Add API key generation endpoint
+- [ ] Add rate limiting per API key
+- [ ] Add usage tracking

src/domains/health/controller.py

@@ -0,0 +1,71 @@
+"""
+Health check controller.
+
+Provides service health and information endpoints.
+"""
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from src.shared.base import BaseController
+from src.shared.config import get_settings
+from src.shared.logging import get_logger, logged
+
+logger = get_logger(__name__)
+settings = get_settings()
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+    status: str
+    version: str
+    service: str
+
+
+class InfoResponse(BaseModel):
+    """Service info response."""
+    service: str
+    version: str
+    status: str
+    docs: str
+    debug: bool
+
+
+class HealthController(BaseController):
+    """Controller for health and info endpoints."""
+
+    def __init__(self):
+        super().__init__(prefix="", tags=["Health"])
+
+    def create_router(self) -> APIRouter:
+        router = APIRouter(tags=self.tags)
+
+        @router.get("/", response_model=InfoResponse, summary="Service information")
+        @logged()
+        async def root():
+            """Get service information."""
+            return InfoResponse(
+                service=settings.app_name,
+                version=settings.app_version,
+                status="healthy",
+                docs="/docs",
+                debug=settings.debug,
+            )
+
+        @router.get("/health", response_model=HealthResponse, summary="Health check")
+        @logged()
+        async def health_check():
+            """
+            Health check endpoint.
+
+            Returns service health status for monitoring and load balancers.
+            """
+            return HealthResponse(
+                status="healthy",
+                version=settings.app_version,
+                service=settings.app_name,
+            )
+
+        return router
+
+
+health_controller = HealthController()

src/domains/health/router.py

@@ -0,0 +1,8 @@
+"""
+Health check routes.
+"""
+from fastapi import APIRouter
+
+from src.domains.health.controller import health_controller
+
+router = health_controller.router

src/domains/router.py

@@ -0,0 +1,26 @@
+"""
+Root router - composes all domain routers.
+
+Import and include domain routers here.
+main.py only includes this root_router.
+"""
+from fastapi import APIRouter
+
+from src.domains.health.router import router as health_router
+# from src.domains.auth.router import router as auth_router
+# from src.domains.agents.router import router as agents_router
+# from src.domains.tools.router import router as tools_router
+
+root_router = APIRouter()
+
+# Health (no prefix - root level)
+root_router.include_router(health_router)
+
+# Auth domain
+# root_router.include_router(auth_router, prefix="/auth", tags=["Auth"])
+
+# Agents domain
+# root_router.include_router(agents_router, prefix="/agents", tags=["Agents"])
+
+# Tools domain
+# root_router.include_router(tools_router, prefix="/tools", tags=["Tools"])

src/domains/tools/README.md

@@ -0,0 +1,70 @@
+# Tools Domain
+
+This domain contains tool implementations for agent use.
+
+## Structure
+
+```
+tools/
+├── router.py        # Tool routes (list, execute)
+├── controller.py    # Tool orchestration
+├── schemas.py       # Tool request/response models
+│
+├── file/            # File operation tools
+│   ├── read.py      # Read file contents
+│   ├── write.py     # Write file contents
+│   └── glob.py      # Find files by pattern
+│
+├── shell/           # Shell execution tools
+│   └── bash.py      # Execute bash commands
+│
+└── search/          # Search tools
+    ├── grep.py      # Search file contents
+    └── web.py       # Web search
+```
+
+## Tool Pattern
+
+Tools are registered with PydanticAI agents via the `@agent.tool` decorator.
+Each tool should:
+
+1. Have clear input/output types
+2. Include a docstring (used by LLM)
+3. Handle errors gracefully
+4. Respect sandbox settings
+
+```python
+from src.shared.config import get_settings
+from src.shared.logging import logged
+
+settings = get_settings()
+
+@logged()
+async def read_file(file_path: str, limit: int = 2000) -> str:
+    """
+    Read contents of a file.
+
+    Args:
+        file_path: Absolute path to the file
+        limit: Maximum lines to read
+
+    Returns:
+        File contents as string
+    """
+    # Check path is allowed
+    if settings.sandbox_enabled:
+        # Validate against allowed_paths
+        pass
+
+    # Read and return
+    pass
+```
+
+## Adding a New Tool
+
+1. Create a new file in appropriate category (file/, shell/, search/)
+2. Implement the tool function with proper types and docstring
+3. Add `@logged()` decorator for timing
+4. Handle sandbox restrictions
+5. Register with agents that need it
+6. Add tests

src/main.py

@@ -0,0 +1,116 @@
+"""
+Webber - Multi-Agent AI Development System
+
+FastAPI application entry point.
+NO routes here - all routes delegated to domain routers.
+"""
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from src.shared.config import get_settings
+from src.shared.logging import setup_logging, get_logger
+from src.shared.exceptions import AppException
+from src.shared.context import user_provider
+from src.shared.auth import validate_api_key
+from src.domains.router import root_router
+
+settings = get_settings()
+setup_logging(settings.log_level)
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application startup and shutdown."""
+    logger.info("=" * 60)
+    logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+    logger.info(f"Debug: {settings.debug}")
+    logger.info(f"Port: {settings.port}")
+    logger.info(f"Ollama: {settings.ollama_url}")
+    logger.info(f"Agent model: {settings.ollama_agent_model}")
+    logger.info("=" * 60)
+
+    # TODO: Initialize resources (LLM clients, etc.)
+
+    yield
+
+    # Cleanup
+    logger.info("Shutting down")
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Multi-Agent AI Development System",
+    docs_url="/docs",
+    redoc_url=None,
+    openapi_url="/openapi.json",
+    lifespan=lifespan,
+    debug=settings.debug,
+)
+
+
+# === Middleware ===
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=settings.cors_credentials,
+    allow_methods=settings.cors_methods,
+    allow_headers=settings.cors_headers,
+)
+
+
+@app.middleware("http")
+async def auth_middleware(request: Request, call_next):
+    """
+    Extract and validate API key, set user context.
+
+    Allows unauthenticated requests - individual routes decide if auth is required.
+    """
+    api_key = request.headers.get("X-API-Key")
+
+    if api_key:
+        user = await validate_api_key(api_key)
+        if user:
+            user_provider.set_user(user)
+
+    try:
+        response = await call_next(request)
+        return response
+    finally:
+        user_provider.clear_user()
+
+
+# === Exception Handlers ===
+
+@app.exception_handler(AppException)
+async def app_exception_handler(request: Request, exc: AppException):
+    """Handle application exceptions."""
+    logger.warning(f"AppException: {exc.error_code} - {exc.message}")
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=exc.to_dict(),
+    )
+
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    """Catch-all exception handler."""
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "InternalServerError",
+            "message": "Internal server error",
+            "details": {"type": type(exc).__name__},
+        }
+    )
+
+
+# === Routes ===
+
+app.include_router(root_router)

src/shared/auth.py

@@ -0,0 +1,106 @@
+"""
+Authentication utilities.
+
+Provides API key validation and integration with external auth services.
+"""
+from typing import Optional
+
+from fastapi import Request, HTTPException, Depends
+from fastapi.security import APIKeyHeader
+
+from src.shared.config import get_settings
+from src.shared.context import User, user_provider
+from src.shared.logging import get_logger
+
+logger = get_logger(__name__)
+settings = get_settings()
+
+# API key header scheme
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+async def validate_api_key(api_key: str) -> Optional[User]:
+    """
+    Validate API key and return User if valid.
+
+    TODO: Integrate with tatlock-ui/core-api for real validation.
+    Currently accepts any non-empty key for development.
+    """
+    if not api_key:
+        return None
+
+    # Development mode: accept any key
+    if settings.debug:
+        logger.debug(f"Debug mode: accepting API key {api_key[:8]}...")
+        return User(
+            id="dev-user",
+            email="dev@localhost",
+            api_key=api_key,
+            tenant_id="dev-tenant",
+            roles=["admin"],
+        )
+
+    # TODO: Production mode - validate against tatlock API
+    # async with httpx.AsyncClient() as client:
+    #     response = await client.get(
+    #         f"{settings.tatlock_api_url}/auth/validate",
+    #         headers={"X-API-Key": api_key}
+    #     )
+    #     if response.status_code == 200:
+    #         data = response.json()
+    #         return User(**data)
+
+    return None
+
+
+async def get_api_key(
+    api_key: Optional[str] = Depends(api_key_header),
+) -> Optional[str]:
+    """FastAPI dependency to extract API key from header."""
+    return api_key
+
+
+async def get_current_user_dep(
+    api_key: Optional[str] = Depends(get_api_key),
+) -> Optional[User]:
+    """
+    FastAPI dependency to get current user from API key.
+
+    Returns None if no valid API key provided.
+    """
+    if not api_key:
+        return None
+    return await validate_api_key(api_key)
+
+
+async def require_auth(
+    user: Optional[User] = Depends(get_current_user_dep),
+) -> User:
+    """
+    FastAPI dependency that requires authentication.
+
+    Raises 401 if no valid API key provided.
+    """
+    if user is None:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or missing API key",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+    return user
+
+
+async def require_admin(
+    user: User = Depends(require_auth),
+) -> User:
+    """
+    FastAPI dependency that requires admin role.
+
+    Raises 403 if user is not admin.
+    """
+    if "admin" not in user.roles:
+        raise HTTPException(
+            status_code=403,
+            detail="Admin access required",
+        )
+    return user

src/shared/base.py

@@ -0,0 +1,74 @@
+"""
+Base classes for controllers and schemas.
+
+All domain controllers and Pydantic models should inherit from these.
+"""
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseController(ABC):
+    """
+    Base controller with lazy router instantiation.
+
+    All domain controllers inherit from this and implement create_router().
+
+    Usage:
+        class UsersController(BaseController):
+            def __init__(self):
+                super().__init__(prefix="/users", tags=["Users"])
+
+            def create_router(self) -> APIRouter:
+                router = APIRouter(prefix=self.prefix, tags=self.tags)
+
+                @router.get("/")
+                async def list_users():
+                    return []
+
+                return router
+
+        users_controller = UsersController()
+    """
+
+    def __init__(self, prefix: str, tags: list[str]):
+        self.prefix = prefix
+        self.tags = tags
+        self._router = None
+
+    @abstractmethod
+    def create_router(self) -> APIRouter:
+        """Create and configure the FastAPI router with all routes."""
+        pass
+
+    @property
+    def router(self) -> APIRouter:
+        """Lazy router instantiation."""
+        if self._router is None:
+            self._router = self.create_router()
+        return self._router
+
+
+class BaseSchema(BaseModel):
+    """
+    Base Pydantic model with standardized configuration.
+
+    All domain schemas should inherit from this.
+    """
+
+    model_config = ConfigDict(
+        strict=False,
+        populate_by_name=True,
+        use_enum_values=True,
+        validate_assignment=True,
+        json_encoders={
+            datetime: lambda v: v.isoformat() if v else None
+        }
+    )
+
+    def dict_without_none(self) -> dict[str, Any]:
+        """Return model as dict, excluding None values."""
+        return {k: v for k, v in self.model_dump().items() if v is not None}

src/shared/config.py

@@ -0,0 +1,76 @@
+"""
+Application configuration via Pydantic Settings.
+
+All settings loaded from environment variables or .env file.
+"""
+import tomllib
+from pathlib import Path
+from functools import lru_cache
+from typing import Optional
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _get_version() -> str:
+    """Load version from pyproject.toml."""
+    pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
+    try:
+        with open(pyproject_path, "rb") as f:
+            return tomllib.load(f).get("project", {}).get("version", "0.0.0")
+    except FileNotFoundError:
+        return "0.0.0"
+
+
+__version__ = _get_version()
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment."""
+
+    # Application
+    app_name: str = "Webber"
+    app_version: str = __version__
+    debug: bool = False
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8086
+
+    # Logging
+    log_level: str = "INFO"
+
+    # CORS
+    cors_origins: list[str] = ["http://localhost:3000", "http://localhost:8080"]
+    cors_credentials: bool = True
+    cors_methods: list[str] = ["*"]
+    cors_headers: list[str] = ["*"]
+
+    # LLM - Ollama (always hot in VRAM on tower-of-joy)
+    ollama_url: str = "http://192.168.86.149:11434"
+    ollama_agent_model: str = "mistral-nemo-large:latest"
+    ollama_embed_model: str = "nomic-embed-text:latest"
+
+    # Auth - Tatlock integration
+    tatlock_api_url: Optional[str] = "http://192.168.86.149:8000"
+    internal_api_key: Optional[str] = None
+
+    # Tool execution
+    tool_timeout_seconds: int = 120
+    sandbox_enabled: bool = True
+    allowed_paths: list[str] = []
+
+    # Sessions
+    session_ttl_hours: int = 24
+    max_context_tokens: int = 128000
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Cached settings singleton."""
+    return Settings()

src/shared/context.py

@@ -0,0 +1,86 @@
+"""
+Request context management.
+
+Provides UserProvider singleton for request-scoped user context.
+Set once per request in middleware, accessible everywhere without
+passing user through function parameters.
+"""
+from dataclasses import dataclass, field
+from typing import Optional
+from contextvars import ContextVar
+
+
+@dataclass
+class User:
+    """Authenticated user context."""
+    id: str
+    email: str
+    api_key: str
+    tenant_id: Optional[str] = None
+    roles: list[str] = field(default_factory=list)
+
+
+_current_user: ContextVar[Optional[User]] = ContextVar('current_user', default=None)
+
+
+class UserProvider:
+    """
+    Singleton for request-scoped user context.
+
+    Set once per request in middleware, accessible everywhere without
+    passing user through function parameters.
+
+    Usage in middleware:
+        user = await validate_api_key(request)
+        user_provider.set_user(user)
+        try:
+            response = await call_next(request)
+        finally:
+            user_provider.clear_user()
+
+    Usage anywhere:
+        from src.shared.context import get_current_user, require_user
+
+        user = get_current_user()  # Returns None if not authenticated
+        user = require_user()      # Raises if not authenticated
+    """
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def set_user(self, user: User) -> None:
+        """Set current user for this request context."""
+        _current_user.set(user)
+
+    def get_user(self) -> Optional[User]:
+        """Get current user (may be None)."""
+        return _current_user.get()
+
+    def clear_user(self) -> None:
+        """Clear current user (call in finally block)."""
+        _current_user.set(None)
+
+    @property
+    def current_user(self) -> Optional[User]:
+        """Property access to current user."""
+        return self.get_user()
+
+
+# Global singleton
+user_provider = UserProvider()
+
+
+def get_current_user() -> Optional[User]:
+    """Get current user or None."""
+    return user_provider.get_user()
+
+
+def require_user() -> User:
+    """Get current user or raise ValueError."""
+    user = user_provider.get_user()
+    if user is None:
+        raise ValueError("No authenticated user in context")
+    return user

src/shared/exceptions.py

@@ -0,0 +1,107 @@
+"""
+Custom exception hierarchy.
+
+All application exceptions inherit from AppException.
+"""
+from typing import Any, Optional
+
+
+class AppException(Exception):
+    """Base exception for application errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        error_code: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code or self.__class__.__name__
+        self.details = details or {}
+        super().__init__(message)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dict."""
+        return {
+            "error": self.error_code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+class NotFoundError(AppException):
+    """Resource not found."""
+
+    def __init__(self, resource: str, identifier: Any):
+        super().__init__(
+            message=f"{resource} not found: {identifier}",
+            status_code=404,
+            details={"resource": resource, "identifier": str(identifier)},
+        )
+
+
+class ValidationError(AppException):
+    """Input validation failed."""
+
+    def __init__(self, message: str, field: Optional[str] = None):
+        super().__init__(
+            message=message,
+            status_code=422,
+            details={"field": field} if field else {},
+        )
+
+
+class AuthenticationError(AppException):
+    """Authentication required or failed."""
+
+    def __init__(self, message: str = "Authentication required"):
+        super().__init__(message=message, status_code=401)
+
+
+class AuthorizationError(AppException):
+    """Permission denied."""
+
+    def __init__(self, message: str = "Permission denied"):
+        super().__init__(message=message, status_code=403)
+
+
+class ConflictError(AppException):
+    """Resource conflict (e.g., duplicate)."""
+
+    def __init__(self, message: str):
+        super().__init__(message=message, status_code=409)
+
+
+class RateLimitError(AppException):
+    """Rate limit exceeded."""
+
+    def __init__(self, retry_after: int = 60):
+        super().__init__(
+            message="Rate limit exceeded",
+            status_code=429,
+            details={"retry_after": retry_after},
+        )
+
+
+class ServiceUnavailableError(AppException):
+    """External service unavailable."""
+
+    def __init__(self, service: str, message: Optional[str] = None):
+        super().__init__(
+            message=message or f"Service unavailable: {service}",
+            status_code=503,
+            details={"service": service},
+        )
+
+
+class TimeoutError(AppException):
+    """Operation timed out."""
+
+    def __init__(self, operation: str, timeout_seconds: float):
+        super().__init__(
+            message=f"Operation timed out: {operation}",
+            status_code=504,
+            details={"operation": operation, "timeout_seconds": timeout_seconds},
+        )

src/shared/logging.py

@@ -0,0 +1,239 @@
+"""
+Centralized logging with temporal benchmarking.
+
+Provides:
+- @logged() decorator for automatic function timing
+- trace_span() context manager for manual instrumentation
+- Trace ID correlation across nested calls
+- Configurable slow/warn thresholds
+"""
+import functools
+import asyncio
+import time
+import logging
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+
+# === Trace Context ===
+
+@dataclass
+class TraceSpan:
+    """Represents a timed execution span."""
+    name: str
+    trace_id: str
+    parent_id: Optional[str] = None
+    span_id: str = field(default_factory=lambda: uuid4().hex[:8])
+    start_time: float = field(default_factory=time.perf_counter)
+    end_time: Optional[float] = None
+
+    @property
+    def duration_ms(self) -> float:
+        """Get duration in milliseconds."""
+        end = self.end_time or time.perf_counter()
+        return (end - self.start_time) * 1000
+
+
+_current_span: ContextVar[Optional[TraceSpan]] = ContextVar('current_span', default=None)
+_trace_id: ContextVar[Optional[str]] = ContextVar('trace_id', default=None)
+
+
+def get_current_trace_id() -> Optional[str]:
+    """Get current trace ID for log correlation."""
+    return _trace_id.get()
+
+
+def get_current_span() -> Optional[TraceSpan]:
+    """Get current trace span."""
+    return _current_span.get()
+
+
+# === Setup ===
+
+def setup_logging(log_level: str = "INFO") -> None:
+    """Configure application logging."""
+    log_dir = Path("logs")
+    log_dir.mkdir(exist_ok=True)
+
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper()),
+        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[
+            logging.StreamHandler(sys.stdout),
+            logging.FileHandler(log_dir / "webber.log", encoding="utf-8")
+        ]
+    )
+
+    # Quiet noisy libraries
+    for name in ["httpx", "httpcore", "uvicorn.access", "uvicorn.error"]:
+        logging.getLogger(name).setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance."""
+    return logging.getLogger(name)
+
+
+# === Decorator ===
+
+def logged(
+    logger: logging.Logger = None,
+    slow_threshold_ms: float = 100.0,
+    warn_threshold_ms: float = 500.0,
+    include_args: bool = False,
+):
+    """
+    Decorator for automatic function logging with temporal benchmarking.
+
+    Args:
+        logger: Logger instance (defaults to module logger)
+        slow_threshold_ms: Log INFO if execution exceeds this (default 100ms)
+        warn_threshold_ms: Log WARNING if execution exceeds this (default 500ms)
+        include_args: Include function arguments in log (careful with sensitive data)
+
+    Usage:
+        @logged()
+        async def my_function(): ...
+
+        @logged(slow_threshold_ms=50, warn_threshold_ms=200)
+        def critical_path(): ...
+    """
+    def decorator(func: Callable):
+        nonlocal logger
+        if logger is None:
+            logger = logging.getLogger(func.__module__)
+
+        func_name = f"{func.__module__}.{func.__qualname__}"
+
+        def _create_span() -> TraceSpan:
+            parent = _current_span.get()
+            trace_id = _trace_id.get() or uuid4().hex[:16]
+            if _trace_id.get() is None:
+                _trace_id.set(trace_id)
+            return TraceSpan(
+                name=func_name,
+                trace_id=trace_id,
+                parent_id=parent.span_id if parent else None,
+            )
+
+        def _log_completion(span: TraceSpan, error: Exception = None):
+            span.end_time = time.perf_counter()
+            duration = span.duration_ms
+            tid = span.trace_id[:8]
+
+            if error:
+                logger.error(
+                    f"[{tid}] {func_name} FAILED after {duration:.2f}ms: {error}",
+                    exc_info=True
+                )
+            elif duration >= warn_threshold_ms:
+                logger.warning(
+                    f"[{tid}] {func_name} SLOW: {duration:.2f}ms (threshold: {warn_threshold_ms}ms)"
+                )
+            elif duration >= slow_threshold_ms:
+                logger.info(f"[{tid}] {func_name} completed in {duration:.2f}ms")
+            else:
+                logger.debug(f"[{tid}] {func_name} completed in {duration:.2f}ms")
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            span = _create_span()
+            token = _current_span.set(span)
+
+            if include_args:
+                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}({args}, {kwargs})")
+            else:
+                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}")
+
+            try:
+                result = await func(*args, **kwargs)
+                _log_completion(span)
+                return result
+            except Exception as e:
+                _log_completion(span, error=e)
+                raise
+            finally:
+                _current_span.reset(token)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            span = _create_span()
+            token = _current_span.set(span)
+
+            if include_args:
+                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}({args}, {kwargs})")
+            else:
+                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}")
+
+            try:
+                result = func(*args, **kwargs)
+                _log_completion(span)
+                return result
+            except Exception as e:
+                _log_completion(span, error=e)
+                raise
+            finally:
+                _current_span.reset(token)
+
+        return async_wrapper if asyncio.iscoroutinefunction(func) else sync_wrapper
+    return decorator
+
+
+# === Context Manager ===
+
+class trace_span:
+    """
+    Context manager for manual span creation.
+
+    Usage:
+        with trace_span("database_query"):
+            result = db.execute(query)
+
+        async with trace_span("llm_call"):
+            response = await agent.run(prompt)
+    """
+
+    def __init__(self, name: str, logger: logging.Logger = None):
+        self.name = name
+        self.logger = logger or logging.getLogger(__name__)
+        self.span: Optional[TraceSpan] = None
+        self.token = None
+
+    def __enter__(self) -> TraceSpan:
+        parent = _current_span.get()
+        trace_id = _trace_id.get() or uuid4().hex[:16]
+        if _trace_id.get() is None:
+            _trace_id.set(trace_id)
+
+        self.span = TraceSpan(
+            name=self.name,
+            trace_id=trace_id,
+            parent_id=parent.span_id if parent else None,
+        )
+        self.token = _current_span.set(self.span)
+        self.logger.debug(f"[{self.span.trace_id[:8]}] -> {self.name}")
+        return self.span
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.span:
+            self.span.end_time = time.perf_counter()
+            duration = self.span.duration_ms
+            tid = self.span.trace_id[:8]
+            if exc_val:
+                self.logger.error(f"[{tid}] {self.name} FAILED: {duration:.2f}ms")
+            else:
+                self.logger.debug(f"[{tid}] {self.name}: {duration:.2f}ms")
+        if self.token:
+            _current_span.reset(self.token)
+        return False
+
+    async def __aenter__(self) -> TraceSpan:
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        return self.__exit__(exc_type, exc_val, exc_tb)