Add LangGraph-based agentic feedback loops to design

[leynos]

Summary

• Introduces LangGraph as the framework for implementing agentic feedback loops across content generation and audio synthesis workflows.
• Updates the system design document to reflect stateful, context-aware, auditable, and scalable multi-agent coordination.
• Aligns architecture with LangChain adapters and hexagonal ports for extensibility.

Changes

Technology Choices

• LangGraph for Agentic Feedback Loops: enables state-driven refinement, contextual audio optimization, observable decision pathways, and scalable multi-agent coordination. Integrates with existing LLM adapters through LangChain while preserving hexagonal architecture via dedicated agent ports.

Component Responsibilities

• Canonical Content Platform:
  • Incorporates LangGraph-based agentic feedback loops for iterative script refinement, integrating QA scores, brand guidelines, and narrative metrics.
  • Maintains agent state graphs tracking revision history, quality improvements, and convergence criteria across generation cycles.
• Quality Assurance Stack:
  • Adds LangGraph-based agents to coordinate QA, compliance checks, and editorial feedback within generation cycles.
• Audio Synthesis and Distribution:
  • TTSPort usage guided by LangGraph audio optimization agents; agents adjust voice parameters, pacing, and music bed selection based on content and previous renders.
  • Implement agent-driven convergence for loudness targets and mastering parameters; distribution metadata remains embedded in outputs.
• Orchestration and Flows:
  • Orchestrator coordinates LangGraph-driven LLMPort interactions, preserving state graphs for iterative refinement; convergence criteria drive regeneration or escalation; editors receive drafts after agent-driven iterations.

QA, Compliance, and Approvals

• Agentic feedback loops surface targeted regeneration requests, enabling traceable QA decisions and approvals.

Audio and Distribution

• Distribution and analytics loops feed listener metrics back into agentic models to continuously optimize future renders.

Rationale

• LangGraph provides persistent state across cycles, auditability of decisions, and scalable coordination across content, audio, and QA.

Testing Plan

• Review the design doc for consistency with current architecture and terminology.
• Validate mappings between LangGraph concepts and existing ports (LLMPort, TTSPort, PreviewPublisherPort).
• Gather feedback from content, QA, and audio teams.

🌿 Generated by Terry

---

ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/84a63402-0101-426e-95ea-0d8fcb195f8e

Summary by Sourcery

Introduce LangGraph-based agentic feedback loops into the episodic podcast system design for content generation and audio synthesis workflows.

New Features:

• Document LangGraph as the framework for stateful, multi-agent feedback loops across content, QA, and audio pipelines.

Enhancements:

• Expand component responsibilities to include agent state tracking, convergence criteria, and targeted regeneration based on QA and analytics.
• Update orchestration flows to describe LangGraph-coordinated LLM interactions and escalation paths with detailed decision logs.
• Extend audio synthesis and distribution flows to include agent-driven optimisation of TTS, mixing, mastering, and continuous improvement from listener analytics.

Documentation:

• Revise the episodic podcast generation system design doc to capture LangGraph technology choices, agent responsibilities, and updated workflow steps.

[sourcery-ai]

Reviewer's Guide

Updates the episodic podcast generation system design doc to introduce LangGraph-based agentic feedback loops across content, QA, and audio pipelines, detailing how LangGraph integrates with existing ports and orchestrator flows while preserving the hexagonal architecture.

Sequence diagram for LangGraph-driven content refinement workflow

sequenceDiagram
  actor Editor
  participant Orchestrator
  participant ContentAgentGraph
  participant LLMPort
  participant LLMProvider
  participant QAStack

  Editor->>Orchestrator: Request_new_episode_draft
  Orchestrator->>ContentAgentGraph: Initialize_state_graph(series_profile, episode_template)
  ContentAgentGraph->>LLMPort: Generate_initial_script(prompts, constraints)
  LLMPort->>LLMProvider: Invoke_model(prompt, token_budget)
  LLMProvider-->>LLMPort: Model_response
  LLMPort-->>ContentAgentGraph: Draft_script_with_confidence_scores

  ContentAgentGraph->>QAStack: Submit_for_preliminary_QA(draft_script)
  QAStack-->>ContentAgentGraph: QA_findings(brand_scores, narrative_issues)

  loop Iterative_refinement_until_convergence
    ContentAgentGraph->>LLMPort: Regenerate_sections(targeted_issues, state_summary)
    LLMPort->>LLMProvider: Invoke_model(refined_prompts)
    LLMProvider-->>LLMPort: Refined_content
    LLMPort-->>ContentAgentGraph: Updated_sections
    ContentAgentGraph->>QAStack: Reevaluate_targeted_sections
    QAStack-->>ContentAgentGraph: Updated_scores_and_feedback
    ContentAgentGraph-->>ContentAgentGraph: Update_state_graph(revisions, metrics, convergence_flags)
  end

  ContentAgentGraph-->>Orchestrator: Final_script_with_state_graph
  Orchestrator-->>Editor: Deliver_draft_with_agent_decision_log

Loading

Sequence diagram for LangGraph-guided audio synthesis and feedback loop

sequenceDiagram
  actor Producer
  participant Orchestrator
  participant AudioAgentGraph
  participant AudioPipeline
  participant TTSPort
  participant TTSProvider
  participant MasteringAgentGraph
  participant DistributionAgentGraph
  participant AnalyticsService

  Orchestrator->>AudioAgentGraph: Start_audio_pipeline(approved_script, series_profile)
  AudioAgentGraph->>TTSPort: Request_narration(script, voice_params, pacing)
  TTSPort->>TTSProvider: Synthesize_narration(audio_request)
  TTSProvider-->>TTSPort: Narration_audio
  TTSPort-->>AudioPipeline: Narration_track

  AudioAgentGraph-->>AudioPipeline: Optimised_mixing_parameters(ducking, crossfades, EQ)
  AudioPipeline->>AudioPipeline: Mix_narration_music_effects

  AudioPipeline->>MasteringAgentGraph: Submit_mix_for_mastering(mix_metrics)
  MasteringAgentGraph->>AudioPipeline: Adjust_loudness_and_compression(target_-16_LUFS)
  loop Iterate_until_loudness_converges
    AudioPipeline->>MasteringAgentGraph: Updated_loudness_stats
    MasteringAgentGraph-->>AudioPipeline: New_mastering_parameters
  end

  AudioPipeline-->>Orchestrator: Mastered_assets(preview, master)
  Orchestrator->>DistributionAgentGraph: Publish_and_monitor(master, metadata)

  DistributionAgentGraph->>AnalyticsService: Register_release(episode_id)
  AnalyticsService-->>DistributionAgentGraph: Listener_metrics(engagement, dropoff_points)
  DistributionAgentGraph-->>AudioAgentGraph: Feedback_for_future_renders(audio_preferences)
  DistributionAgentGraph-->>ContentAgentGraph: Feedback_for_future_scripts(optional)

  Producer->>Orchestrator: Provide_approval_or_change_requests
  Orchestrator-->>AudioAgentGraph: Update_agent_state_with_producer_feedback

Loading

Class diagram for LangGraph-based agents and ports in episodic podcast system

classDiagram
  class Orchestrator {
    +startContentWorkflow(seriesProfileId, episodeTemplateId)
    +startAudioWorkflow(approvedScriptId, seriesProfileId)
    +loadSeriesProfile(seriesProfileId)
    +loadEpisodeTemplate(episodeTemplateId)
  }

  class AgentGraph {
    +id
    +stateStore
    +convergenceCriteria
    +initializeState(context)
    +runIteration(context)
    +hasConverged()
    +getDecisionLog()
  }

  class ContentAgentGraph {
    +revisionHistory
    +qualityMetrics
    +brandComplianceScores
    +generateInitialDraft(seriesProfile, episodeTemplate)
    +refineDraftWithQAFindings(qaFindings)
  }

  class AudioAgentGraph {
    +voiceParameters
    +pacingParameters
    +mixingPreferences
    +selectVoiceParameters(scriptMetadata, seriesProfile)
    +optimiseMixParameters(previousRenders, approvalHistory)
  }

  class MasteringAgentGraph {
    +targetLoudness
    +compressionSettings
    +validateLoudness(mixMetrics)
    +adjustMasteringParameters(mixMetrics)
  }

  class DistributionAgentGraph {
    +engagementMetrics
    +dropoffPatterns
    +updateModelsFromAnalytics(analyticsSnapshot)
    +proposeFutureContentAdjustments()
    +proposeFutureAudioAdjustments()
  }

  class CanonicalContentPlatform {
    +generateDraftWithAgents(seriesProfile, episodeTemplate)
    +persistGenerationRun(prompt, response, costs, agentState)
  }

  class QAStack {
    +runPreliminaryChecks(script)
    +computeBrandGuidelineScores(script)
    +evaluateNarrativeFlow(script)
  }

  class AudioPipeline {
    +requestNarration(ttsRequest)
    +mixNarrationAndMusic(mixParameters)
    +applyMastering(masteringParameters)
  }

  class LLMPort {
    +invokeModel(prompt, tokenBudget, modelId)
  }

  class TTSPort {
    +synthesize(script, voiceParams, pacingParams)
  }

  class PreviewPublisherPort {
    +publishPreview(episodeId, assetLocation)
    +publishMaster(episodeId, assetLocation, metadata)
  }

  class AnalyticsService {
    +getListenerMetrics(episodeId)
  }

  Orchestrator --> CanonicalContentPlatform
  Orchestrator --> AudioPipeline
  Orchestrator --> ContentAgentGraph
  Orchestrator --> AudioAgentGraph

  AgentGraph <|-- ContentAgentGraph
  AgentGraph <|-- AudioAgentGraph
  AgentGraph <|-- MasteringAgentGraph
  AgentGraph <|-- DistributionAgentGraph

  ContentAgentGraph --> LLMPort
  ContentAgentGraph --> QAStack
  ContentAgentGraph --> CanonicalContentPlatform

  AudioAgentGraph --> TTSPort
  AudioAgentGraph --> AudioPipeline

  MasteringAgentGraph --> AudioPipeline

  DistributionAgentGraph --> AnalyticsService
  DistributionAgentGraph --> ContentAgentGraph
  DistributionAgentGraph --> AudioAgentGraph

  AudioPipeline --> PreviewPublisherPort
  CanonicalContentPlatform --> QAStack

Loading

File-Level Changes

Change	Details	Files
Document LangGraph as the primary framework for agentic feedback loops and multi-agent coordination.	Add a Technology Choices subsection introducing LangGraph for agentic feedback loops. Describe capabilities such as state-driven iterative refinement, contextual audio optimisation, observable decision pathways, and scalable multi-agent coordination. Explain integration with existing LLM adapters via LangChain and preservation of hexagonal architecture through dedicated agent ports.	docs/episodic-podcast-generation-system-design.md
Extend Canonical Content Platform responsibilities to use LangGraph agents for iterative script refinement and state tracking.	Specify that the platform employs LangGraph-based feedback loops integrating QA scores, brand guidelines, and narrative metrics. Clarify that agent state graphs maintain revision history, quality improvements, and convergence criteria across generation cycles.	docs/episodic-podcast-generation-system-design.md
Update orchestration and content generation flow to be LangGraph-driven and stateful.	Replace the simple LLMPort invocation step with LangGraph agents coordinating LLM calls and maintaining state graphs. Add steps where agents analyse preliminary QA findings, trigger targeted regeneration, and apply convergence criteria to decide between regeneration and escalation. Indicate that editors now receive drafts after agent-driven iterations and with detailed agent decision logs in divergent cases.	docs/episodic-podcast-generation-system-design.md
Enhance audio synthesis and distribution design with LangGraph-based optimisation and feedback loops.	Introduce LangGraph audio optimisation agents guiding TTSPort usage for narration requests. Describe agents that tune voice parameters, pacing, emotional tone, and mixing parameters based on prior renders and producer feedback. Add mastering agents that verify and iterate toward loudness targets and compression settings. Document distribution agents that use listener analytics to close the feedback loop and optimise future audio renders.	docs/episodic-podcast-generation-system-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch terragon/add-langgraph-feedback-loop-a4mw1h

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Add LangGraph agentic feedback loops to the episodic podcast system design in episodic-podcast-generation-system-design.md

Adds a Technology Choices section specifying LangGraph for state-driven agent workflows, updates orchestrator and audio pipeline responsibilities to use LangGraph-based iterative refinement with QA and brand metrics, and revises generation and distribution workflows to replace direct LLM calls with coordinated agents and logged decision loops.

📍Where to Start

Start with the Technology Choices and updated workflows in episodic-podcast-generation-system-design.md.

---

Macroscope summarized e7e20b9.