From Document to Report in 30 Minutes

Document processing is one of the most common enterprise AI use cases. Every organization has documents that need to be read, analyzed, and transformed into structured reports -- compliance reviews, financial summaries, research digests, contract analyses. The challenge is not building a demo that works once; it is building a system that works reliably in production, with human oversight, real-time feedback, and full observability.

This tutorial walks through building a complete document-to-report pipeline using FireFoundry. You will upload a document, extract its content, analyze it with an LLM, generate a structured report, run it through a human review cycle, and produce a final PDF. The full tutorial is a 13-part series that takes you from your first entity to a deployed consumer application. This article gives you the high-level walkthrough so you understand the architecture before diving into the code.

---

What We're Building

The finished application is a document-to-report generator with these capabilities:

• 1 Document upload -- accepts PDFs, Word files, and plain text through a REST API
• 2 Content extraction -- uses OCR and structural parsing to pull text from uploaded files
• 3 AI analysis -- an LLM processes the extracted content and generates a structured HTML report
• 4 Human review -- a reviewer approves the report or provides feedback for revision
• 5 Iterative refinement -- the LLM incorporates feedback and produces updated versions
• 6 PDF generation -- the final approved report is converted to a downloadable PDF

All of this runs on FireFoundry's infrastructure with persistent state, real-time progress streaming, and full telemetry -- the same qualities you need for any production AI system.

---

Key Concepts

Before walking through the pipeline, here are the FireFoundry concepts that make this architecture possible.

---

The Pipeline: Step by Step

Here is the full flow from document upload to final PDF. Each step maps to one or more parts of the 13-part tutorial.

---

Code Highlights

Here are three code patterns from the tutorial that illustrate how FireFoundry's architecture keeps things clean.

Entity with ReviewableEntity

The top-level workflow entity extends ReviewableEntity, which handles the entire review loop. You provide the wrapped entity class, and the framework manages creating review steps, storing feedback, and re-running on rejection.

@EntityMixin({
  specificType: 'ReportReviewWorkflowEntity',
  generalType: 'ReportReviewWorkflowEntity',
  allowedConnections: {}
})
export class ReportReviewWorkflowEntity extends ReviewableEntity<
  ReportReviewWorkflowRETH
> {
  // Tell the framework which entity to run inside the review loop
  protected override get wrappedEntityClass() {
    return 'ReportEntity';
  }

  // Configure the review step prompt
  protected override get reviewPrompt(): string {
    return 'Please review the generated report. Approve if it meets ' +
      'your requirements, or provide feedback for revision.';
  }

  // Extract the result to show the reviewer
  protected override createResultEntity(
    result: REPORT_WORKFLOW_OUTPUT
  ) {
    return {
      html_content: result.html_content,
      pdf_working_memory_id: result.pdf_working_memory_id
    };
  }
}

Bot with Structured Output Validation

Bots use Zod schemas with withSchemaMetadata to define exactly what the LLM should return. The StructuredOutputBotMixin automatically injects the schema into the prompt and validates the response. Field ordering matters -- placing reasoning before html_content forces the LLM to plan before generating.

import { z } from 'zod';
import { withSchemaMetadata } from '@firebrandanalytics/ff-agent-sdk';

export const ReportOutputSchema = withSchemaMetadata(
  z.object({
    reasoning: z.string()
      .describe('Your thought process for structuring this report. '
        + 'Explain what sections you chose and why.'),
    html_content: z.string()
      .describe('Complete HTML document with embedded CSS styling. '
        + 'Must include DOCTYPE, html, head with style tag, and body.')
  }),
  'Your final output',
  'AI-generated HTML report with reasoning'
);

export type REPORT_OUTPUT = z.infer<typeof ReportOutputSchema>;

SSE Progress Streaming Endpoint

The consumer backend bridges the agent bundle's async iterator to the browser via Server-Sent Events. The client connects once and receives typed progress envelopes in real time -- no polling, no WebSocket complexity.

export async function GET(request: NextRequest, { params }) {
  const { id: entityId } = await params;
  const client = new RemoteAgentBundleClient(AGENT_BUNDLE_URL);

  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
      const send = (data: any) =>
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify(data)}\n\n`)
        );

      // Acknowledge connection
      send({ type: 'ACK', entity_id: entityId });

      // Attach to the running workflow's iterator
      const iterator = await client.start_iterator(
        entityId, 'start', []
      );

      for await (const envelope of iterator) {
        send(envelope);  // INTERNAL_UPDATE, VALUE, WAITING, etc.
      }

      send({ type: 'DONE' });
      controller.close();
    }
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/event-stream' }
  });
}

---

What Makes This Production-Ready

A working demo and a production system are very different things. Here is what this architecture provides beyond the happy path.

---

Architecture Overview

The final architecture uses entity delegation to break the workflow into composable stages. The review workflow entity wraps the report entity, which in turn orchestrates text extraction, AI generation, and PDF conversion as child stages.

Document Upload
       |
       v
ReportReviewWorkflowEntity (ReviewableEntity)
       |
       |-- Stores document in Working Memory
       |-- Creates and delegates to ReportEntity
       |
       v
ReportEntity (RunnableEntity orchestrator)
       |
       |-- Stage 1: Extract text (doc-proc-client)
       |-- Stage 2: Generate HTML (ReportGenerationEntity -> ReportGenerationBot)
       |-- Stage 3: Convert to PDF (doc-proc-client)
       |
       v
ReviewStep
       |
       |-- Human approves or requests changes
       |-- If rejected: re-runs with feedback
       |
       v
Final Result (PDF in Working Memory)

---

Try It Yourself

This article covered the high-level architecture and key patterns. The full 13-part tutorial walks you through every line of code, from scaffolding the project to deploying a consumer application with real-time streaming and review workflows.

Start the full tutorial at the FireFoundry public docs repository under the tutorials section. Each part builds on the previous one, and every step produces a deployable application you can test with CLI tools before moving on.

FireFoundry is currently in private beta. If you want to build this pipeline or explore other agent architectures, request beta access and our team will get you set up.