Project Guide | DocFlow Agent

DocFlow Agent

A document-to-learning pipeline that turns uploaded files into structured extraction, grounded Q&A, and LMS-ready exports (SCORM / IMS CC).

System Overview

Lens	Decision signal
Users	Education, enablement, and internal training teams that need document ingestion to become LMS-ready learning assets without a manual content factory.
Product proof	The demo, workflow loop, and static proof surface show the current product direction without extra claims.
Technical proof	Demo mode, health endpoints, runtime scorecards, schemas, export timeline, and tests make the product inspectable without external API keys.
Safety posture	Session-scoped provider settings, grounded citations, structured errors, and local/Ollama fallback reduce hallucination and credential risk.

Evaluation Path

Start here: Run demo mode, upload a sample document, and inspect citations plus LMS export posture.
Local demo: Run DOCUAGENT_DEMO_MODE=1 python3 main.py, then open http://localhost:8000.
Checks: Run make verify; it executes lint, tests, smoke checks, and demo-safe verification.

Technical Notes

Technical guide summarizes the system scope, first files to inspect, verification commands, and known boundaries.
Quality notes lists the local checks, CI surface, and release expectations for this repository.
Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

What it does

Upload a document and the system will:

Parse and extract structured content (schema-based JSON)
Generate summaries with document-grounded Q&A
Provide page-level source citations for answers
Build learning content (objectives, quiz, flashcards, activities)
Export to LMS formats (SCORM 1.2/2004, IMS CC 1.1/1.3)
Optionally use Ollama for local text generation

Quick Start

cp .env.example .env          # adjust if needed
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -U pip
python3 -m pip install -e ".[dev]"

Run in demo mode (no API keys needed):

DOCUAGENT_DEMO_MODE=1 python3 main.py

Run with Upstage API:

UPSTAGE_API_KEY="<your_key>" python3 main.py

Run with Ollama (local LLM):

UPSTAGE_API_KEY="<your_key>" \
DOCUAGENT_LLM_PROVIDER=ollama \
OLLAMA_BASE_URL="http://127.0.0.1:11434" \
OLLAMA_MODEL="llama3.2:latest" \
python3 main.py

Open http://localhost:8000

API Endpoints

Endpoint	Description
`GET /healthz`	Runtime mode, provider status, queue pressure
`GET /api/runtime/brief`	Operator workflow summary and config
`GET /api/runtime/scorecard`	Queue pressure, route health overview
`GET /api/export-timeline`	Recent analyses, job state, and artifact handoff posture
`GET /api/review-pack`	Pipeline summary with export routes
`GET /api/schema/analysis-report`	Analysis payload schema
`GET /api/metrics`	Runtime metrics
`POST /api/analyze`	Run document analysis
`POST /api/analyze/jobs`	Async analysis with polling/cancellation
`GET /api/export/scorm`	Export learning package

Architecture

main.py: FastAPI backend with Upstage/Ollama integrations and export builders
citation_utils.py: Grounded source-citation extraction and scoring
exceptions.py: Custom exception hierarchy for each pipeline stage
logging_config.py: JSON-structured logging and pipeline stage tracker
index.html: Frontend UI
assets/: Demo documents and UI assets
tests/: 155 tests covering extraction, Q&A, export, edge cases, and logging

Key features

Demo mode: Runs fully offline without external API keys (DOCUAGENT_DEMO_MODE=1)
Async jobs: Supports polling, cancellation, and concurrency limits
Session-scoped config: API keys and provider settings are per-session, not persisted
Citations: Q&A answers include source citations tied to document content
Optional GCP artifact export: when DOCUAGENT_GCP_STORAGE_BUCKET is configured and gcloud auth is available, /api/analyze uploads a review-safe analysis JSON artifact to GCS

Dev / Tests

python3 -m pip install -r requirements-dev.txt
ruff check .
ruff format --check .
pytest -q

Deployment

CI: .github/workflows/ci.yml
Cloudflare Pages: static site with policy pages
Terraform skeleton: infra/terraform/

Docs

English: README.en.md
Korean: README.ko.md
Ops runbook: docs/ops/RUNBOOK.md

Glossary

LMS: Learning Management System
SCORM: Sharable Content Object Reference Model
IMS CC: IMS Common Cartridge

Cloud + AI Architecture

Cloud + AI architecture blueprint
Machine-readable architecture manifest
Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

Service Architecture

Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.