External AI Integration Configs

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt
• apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt
• apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt
• apps/api/src/main/resources/application.yml
• apps/web/src/routes/settings/index.tsx
• apps/web/src/lib/api/types.ts
• AGENT_NOTES.md

External AI Integration Configs represent the architectural framework and configuration parameters used by Briefy to interact with various Large Language Model (LLM) providers and AI-driven services. This system manages provider-specific credentials, model selections for different use cases (such as topic extraction and research synthesis), and runtime execution parameters for AI agents.

The integration is divided between backend infrastructure logic—handling provider dispatching and execution loops—and a frontend settings interface that allows users or administrators to configure API keys and model preferences.

Core Provider Infrastructure

The system supports multiple AI providers through an adapter pattern, primarily managed by the AiAdapter. Configurations for these providers are defined in the application environment and surfaced to the UI for selection.

Supported Providers and Models

Briefy integrates with several major AI platforms, each with specific default models and endpoint configurations.

Provider ID	Default/Common Models	Configuration Key
google_genai	gemini-2.5-flash, gemini-3-flash-preview	GOOGLE_GENAI_API_KEY
zhipuai	glm-4.7-flash	ZHIPUAI_API_KEY
minimax	MiniMax-M2.5	MINIMAX_API_KEY

Sources: apps/api/src/main/resources/application.yml:33-55, apps/web/src/lib/api/types.ts:219-221

AI Use Case Routing

The system routes specific tasks to designated provider/model pairs. These mappings are stored as AiUseCaseSettingDto objects and can be updated via the settings interface.

• Topic Extraction: Extracts concise topics from source content.
• Source Formatting: Formats raw extracted text into clean structures.
• Briefing Planning: Uses models like gemini-3-flash-preview to generate research plans.
• Subagent Execution: Runs specific research personas to investigate data.
• Synthesis: Reconciles multi-persona outputs into a cohesive briefing.

Sources: apps/web/src/lib/api/types.ts:233-237, apps/api/src/main/resources/application.yml:195-212

Briefing Execution & Agent Configs

Briefy employs an agentic workflow where "Subagents" (AI personas) perform research tasks using tools before a final synthesis step.

Subagent Tool Loop

The AiSubagentExecutionRunner manages a loop where the LLM can request tool calls (e.g., web search or fetching) before producing a final output. This process is governed by a specific AiRunnerConfig.

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:38-95

Execution Parameters

The behavior of the AI runners is controlled by properties defined in the backend YAML configuration:

• max-tool-calls: Maximum iterations a subagent can perform (default: 8).
• mode: Execution strategy, such as sequential.
• global-timeout-seconds: Total time allowed for a briefing run (default: 180s).
• retry: Specific delays for transient errors or HTTP 429 (Rate Limiting).

Sources: apps/api/src/main/resources/application.yml:198-212, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:233-237

Frontend Configuration Interface

The settings page provides a centralized UI for managing AI provider credentials and use-case model selections.

AI Model Management Logic

The frontend filters available models based on the selected provider and verifies if a provider is "configured" (i.e., has an API key on the server) before allowing it to be saved for a use case.

Extraction Provider Settings

Beyond LLMs, the system configures external extraction services used to ingest source content.

Provider	Purpose	Configurable Fields
Firecrawl	Clean markdown extraction	API Key, Toggle Enable
X API	Extracting X (Twitter) threads	Bearer Token, Toggle Enable
ElevenLabs	Text-to-speech (Narration)	API Key, Toggle Enable
Jsoup	Fallback web extraction	Always Active (Zero-config)

Sources: apps/web/src/routes/settings/index.tsx:425-550

Implementation Details & Constraints

Topic Extraction Configuration

The TopicSuggestionService uses a specific system prompt and model selection to generate 1-5 concise topics. It is configured to avoid holding database transactions during long AI calls to prevent connection pool exhaustion.

// Example of Use Case Resolution in Topic Service
val selection = userAiSettingsService.resolveUseCaseSelection(userId, UserAiSettingsService.TOPIC_EXTRACTION)
val raw = aiAdapter.complete(
    provider = selection.provider,
    model = selection.model,
    prompt = userPrompt,
    systemPrompt = systemPrompt,
    useCase = UserAiSettingsService.TOPIC_EXTRACTION
)

Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt:140-147, AGENT_NOTES.md:120-125

Synthesis Logic

The AiSynthesisExecutionRunner synthesizes multi-persona research. It requires the LLM to return valid JSON following a strict schema including markdownBody, references, and conflictHighlights.

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt:37-53

Summary

The External AI Integration Configs provide a robust, multi-provider system that powers the core "intelligent" features of Briefy. By separating provider adapters, runtime execution runners, and user-facing settings, the architecture allows for flexible model swapping and reliable execution of complex AI agent workflows. Key aspects include a sophisticated subagent tool loop, granular use-case routing, and an admin-friendly configuration interface for managing API credentials.