Briefing Orchestration Engine

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/BriefingGenerationService.kt
• apps/api/src/main/kotlin/com/briefy/api/application/briefing/BriefingService.kt
• 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/briefing/AiBriefingPlanGenerator.kt
• apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/briefing/Briefing.kt
• apps/api/src/main/resources/application.yml

The Briefing Orchestration Engine is a multi-stage system responsible for generating structured, evidence-grounded briefings from source content. It manages the lifecycle of a briefing from initial planning and persona assignment to subagent execution and final synthesis. The engine utilizes Large Language Models (LLMs) to perform research tasks, search the web, and reconcile conflicting information into a cohesive markdown document.

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/BriefingGenerationService.kt, apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/briefing/Briefing.kt

Briefing Lifecycle and State Machine

A briefing progresses through several distinct states, managed by the Briefing domain entity. The orchestration starts with a plan that requires user approval before execution begins.

The diagram shows the state transitions of a Briefing entity from creation to completion or failure.
Sources: apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/briefing/Briefing.kt:45-100

Key States

State	Description
PLAN_PENDING_APPROVAL	Initial state where AI has proposed a research plan (personas and tasks).
APPROVED	User has confirmed the plan; the briefing is queued for background processing.
GENERATING	Orchestration is actively running subagents and synthesis runners.
READY	Generation is successful; markdown content and citations are available.
FAILED	An error occurred during planning or execution.

Sources: apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/briefing/Briefing.kt:18-35, apps/api/src/main/kotlin/com/briefy/api/application/briefing/BriefingService.kt:70-105

Planning Phase

The planning phase determines the "research strategy" for a briefing based on the Enrichment Intent (e.g., Deep Dive, Truth Grounding, Contextual Expansion).

1. AI Planning: If enabled, the AiBriefingPlanGenerator uses an LLM to select between 2 and 5 personas from a catalog and assign specific tasks based on the source content.
2. Deterministic Fallback: If AI planning is disabled or fails, the DeterministicBriefingPlanGenerator provides a static set of steps (e.g., "Claim Auditor", "Synthesis Writer").

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiBriefingPlanGenerator.kt:20-40, apps/api/src/main/kotlin/com/briefy/api/application/briefing/DeterministicBriefingPlanGenerator.kt:12-45

Subagent Execution

The AiSubagentExecutionRunner performs the individual tasks defined in the plan. Each subagent operates within a "Tool Loop," allowing the LLM to interact with external tools.

Subagent Tool Loop Flow

This flowchart illustrates the iterative process where a subagent uses internal context and optional web tools to complete its assigned research task.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:37-100

Available Tools

• web_search: Searches the web for additional information using a query.
• web_fetch: Fetches the full text of a specific URL discovered during search.

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

Synthesis and Grounding

Once subagents complete their tasks, the AiSynthesisExecutionRunner aggregates their outputs into a final document.

Synthesis Requirements

The synthesis phase is governed by strict system prompts to ensure quality and accuracy:

• Explicit Disagreement: Disagreements between subagents or sources must be resolved explicitly.
• Evidence Grounding: Claims must be backed by citations; speculation is avoided.
• Conflict Highlights: If significant contradictions exist, they are extracted into a structured conflictHighlights JSON array.

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

Reference Merging

The engine deduplicates and merges references from multiple subagents.

private fun mergeReferences(
    primary: List<BriefingReferenceCandidate>,
    fallback: List<BriefingReferenceCandidate>
): List<BriefingReferenceCandidate> {
    val deduped = linkedMapOf<String, BriefingReferenceCandidate>()
    (primary + fallback).forEach { candidate ->
        val url = candidate.url.trim()
        if (url.isBlank()) return@forEach
        val key = url.lowercase()
        if (deduped.containsKey(key)) return@forEach
        deduped[key] = candidate
    }
    return deduped.values.toList()
}

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

Configuration

The orchestration behavior is controlled via Spring properties in application.yml.

Property	Default	Description
briefing.execution.enabled	true	Whether to use the full multi-agent orchestrator.
briefing.execution.mode	sequential	Execution pattern for subagents.
briefing.execution.ai.model	gemini-2.5-flash	The primary model used for subagents and synthesis.
briefing.execution.ai.max-tool-calls	8	Budget for subagent web tools per task.
briefing.planning.provider	google_genai	Provider for generating the research plan.

Sources: apps/api/src/main/resources/application.yml:195-225

Technical Summary

The Briefing Orchestration Engine transitions the system from simple summarization to complex research. By separating the process into Planning, Execution (Subagents), and Synthesis, the system can handle large source sets, perform external verification, and identify conflicting information with high confidence thresholds (typically >0.75).

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/BriefingGenerationService.kt:190-200, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:25-35