qfa.services.orchestrator#

Orchestrator service — core business logic for feedback analysis.

Assembles prompts, enforces token limits, filters prompt injection, manages retries with exponential backoff, and enforces deadlines.

Classes

Orchestrator(llm, anonymizer, settings, ...)

Core orchestration service for feedback analysis.
class qfa.services.orchestrator.Orchestrator(llm: LLMPort, anonymizer: AnonymizationPort, settings: OrchestratorSettings, llm_timeout_seconds: float, max_total_tokens: int)[source]#

Bases: object

Core orchestration service for feedback analysis.

Assembles prompts from feedback records, validates input, calls the LLM through the LLMPort, and manages retries with exponential backoff and deadline enforcement.

Parameters:

  • llm (LLMPort) – The LLM provider adapter.

  • anonymizer (AnonymizationPort) – The anonymisation adapter used to redact PII before LLM calls.

  • settings (OrchestratorSettings) – Configuration for the orchestrator behaviour.

  • llm_timeout_seconds (float) – Maximum time in seconds for a single LLM call.

  • max_total_tokens (int) – Maximum estimated total tokens for a single request.

async analyze(request: AnalysisRequestModel, deadline: datetime, anonymize: bool = True) → AnalysisResultModel[source]#

Analyze a batch of feedback records.

Parameters:

  • request (AnalysisRequest) – The analysis request containing feedback records and prompt.

  • deadline (datetime) – Absolute UTC deadline by which the analysis must complete.

Returns:

The complete analysis result.

Return type:

AnalysisResult

Raises:
async summarize(request: SummaryRequestModel, deadline: datetime, anonymize: bool = True) → SummaryResultModel[source]#

Summarize each submitted feedback record individually.

Parameters:

  • request (SummaryRequest) – The summarization request containing feedback records and options.

  • deadline (datetime) – Absolute UTC deadline by which summarization must complete.

Returns:

The per-feedback-record summaries and titles.

Return type:

SummaryResult

Raises:

AnalysisError – When the LLM returns invalid output or another non-recoverable error occurs.

async summarize_aggregate(request: SummaryRequestModel, deadline: datetime, anonymize: bool = True) → AggregateSummaryResultModel[source]#

Summarize multiple feedback records as a single aggregate summary.

Parameters:

  • request (SummaryRequest) – The summarization request containing feedback records and options.

  • deadline (datetime) – Absolute UTC deadline by which summarization must complete.

Returns:

A single aggregate summary with themes ordered by frequency.

Return type:

AggregateSummaryResult

async assign_codes(request: CodingAssignmentRequestModel, deadline: datetime, anonymize: bool = True) → CodingAssignmentResultModel[source]#

Assign hierarchical codes to each feedback record.

Parameters:

  • request (CodingAssignmentRequest) – Feedback records, coding framework, max_codes, and tenant id.

  • deadline (datetime) – Absolute UTC deadline by which all records must be coded.

Returns:

Per-record leaf codes from classify_feedback.

Return type:

CodingAssignmentResult

Raises: