ai

The AI submodule provides a unified gateway for interacting with large language models across multiple providers. Rather than coupling your application to a single AI vendor, HedHog abstracts provider-specific APIs behind a common interface, making it straightforward to switch between OpenAI GPT models and Google Gemini without changing application code. Providers and models are resolved from Integration Profiles or environment variables, with agent-level overrides taking precedence over global defaults.

The submodule supports two interaction modes. Direct chat sends a one-shot message to the default provider and returns a single response. AI Agents are named, persistently configured entities stored in the database — each agent carries its own provider, model, system prompt (instructions), and slug identifier. This lets product teams define purpose-specific assistants — a data-analysis agent, a customer-support bot, a content-generation pipeline — that remain consistent across deployments without hardcoding configuration into client code.

Both the direct-chat and agent-chat endpoints accept an optional file_id parameter. When provided, the API retrieves the file from the File submodule and includes its content as context in the LLM request, enabling document summarization, code review, and content extraction workflows without building a separate ingestion pipeline.

All AI operations are also exposed as MCP tools (core.ai.*), meaning any MCP-compatible AI assistant — Claude Desktop, Cursor, a custom agent — can manage agents and send messages through the same permission-controlled surface as HTTP callers.