Content Generation System
CGS is an asynchronous, AI-driven educational content authoring backend. Its production LMS path turns instructor requirements and reference PDFs into proposed TipTap content. A separate course-agent workflow supports stateful course planning, lesson generation, validation, review, and rendering.
I contributed to backend engineering for CGS as an AI Engineering Intern at Fusemachines Nepal. It is a collaborative, company-owned system—not a project I independently created or own. This portfolio frontend is separate from the Python API service.
I contributed to a collaborative, company-owned system. The work below names implementation areas I owned or contributed to; it is not a claim that I independently created or owned CGS.
- Individual implementation work: author normalization and filtering, AST and rendering support, authoring endpoints and generation ownership, prompts and validators, web research integration, and retrieval/document-processing components.
- Collaborative contribution: Python/FastAPI backend behavior, LangGraph orchestration and multi-step generation paths, LLM integration, structured generation and validation, and PostgreSQL/vector retrieval architecture.
- Team/company-owned context: the complete CGS platform, LMS integration, production infrastructure, review workflows, and overall system architecture.
System architecture
CGS is the Python backend behind the LMS authoring flow. It exposes authoring, generation, review, drafts, documents, and agent-session APIs. The course-agent graph coordinates stateful stages in a separate workflow; it is not one enormous prompt.
This is a layer map, not a single request flow. The production LMS path and the separate course-agent path are shown in the diagrams below.
Core generation architecture
Pipeline A uses an asynchronous in-process task and returns normalized editor content. Pipeline B uses LangGraph for stateful workflow stages and conditional transitions; generation nodes use configured LLM providers, and PostgreSQL stores application data and workflow checkpoints.
Implemented Core generation workflows
REQUEST AND ORCHESTRATION- LMS frontend
- LMS backend
- CGS FastAPI
- Authentication + request validation
- Execution path selection
- Pipeline A · LMS authoring
- Asynchronous in-process task
- pypdfium2 PDF text
- LLM generation
- TipTap HTML / SuggestedPatch
- Client polling
- Pipeline B · course agent
- LangGraph StateGraph
- Clarification + outline review
- Parallel lesson generation
- Human review and retries
- PostgreSQL checkpoints + in-memory SSE
Pipeline B is separate from the active LMS authoring UI. The active LMS authoring path does not call the LangGraph course-agent workflow.
- 01Preflight
- 02Optional web research
- 03Blueprint
- 04Writing
- 05Quiz audit
- 06Critic
- 07Revision when required
- 08Quality validation
- 09Rendering
Technology stack
The backend is organized around a typed asynchronous API, graph-based orchestration, and a relational database extended for vector retrieval.
Backend and API
- Python 3.12
- FastAPI · asynchronous REST API
- Uvicorn · ASGI server
- Pydantic V2 · schemas and validation
- SQLAlchemy 2.x · database access
- Alembic · schema migrations
Agent orchestration
- LangGraph · stateful graph execution
- Defined nodes and conditional transitions
- Parallel lesson generation where appropriate
- PostgreSQL-backed workflow checkpoints
Database and retrieval
- PostgreSQL 16 · primary relational store
- pgvector · 768-dimensional embeddings
- HNSW · approximate vector search with cosine distance
- PostgreSQL Full-Text Search · sparse retrieval
- GIN index · full-text search support
- RRF · dense and sparse rank fusion
- Optional cross-encoder reranking
AI and external services
- OpenAI-compatible LLM interfaces
- Google Gemini-compatible endpoint configuration
- Configurable planning, writing, judging, summarization models
- OpenAI-compatible embedding endpoints
- Tavily · optional web research
Document processing
- Docling · layout, OCR, reading order, tables
- pypdfium2 · PDF text extraction
- Hugging Face tokenizer and model ecosystem
- CPU-based PyTorch configuration for Linux
Supporting infrastructure
- Redis · optional temporary state and coordination
- Docker and Docker Compose · containerization
- GitHub Actions · deployment workflows
How AI generation works
The course-agent path uses a LangGraph graph that moves through clarification, outline review, lesson generation, and finalization. State and conditional transitions coordinate each stage, with parallel lesson execution where appropriate. The LMS authoring path is separate: it runs an asynchronous generation task and returns normalized editor content.
Pipeline B · course-agent workflow
Per-lesson generation pipeline
Each lesson follows a nine-stage pipeline. Optional steps are only active when enabled in the relevant execution path; stages do not necessarily map one-to-one to separate models.
- 01Preflight
Check inputs, constraints, and generation readiness.
- 02Web research
Retrieve external information when research is enabled.
- 03Blueprint
Establish the lesson structure before drafting.
- 04Writing
Produce the lesson content from the approved context.
- 05Quiz audit
Review generated assessment content.
- 06Critic
Evaluate the draft and identify quality issues.
- 07Revision
Address identified issues within a bounded retry policy.
- 08Quality validation
Check the final structured content.
- 09Rendering
Translate the structured representation into its output form.
Structured content, not free-form text
Generated lessons use Pydantic models and a canonical set of 15 content block types instead of unrestricted plain text. This gives the system a consistent contract to validate, normalize, serialize, and pass to downstream consumers.
The rendering layer translates the structured content representation into consumable HTML. Content types stay explicit through validation and serialization rather than being inferred from a single text blob.
Retrieval-augmented generation
The retrieval subsystem combines dense semantic search with PostgreSQL full-text search. It is implemented as a backend capability; the active LMS authoring workflow does not yet call the full document-ingestion and hybrid-retrieval path.
Extract → semantically chunk → preserve heading context → embed → store chunks and vectors in PostgreSQL
Embed query → dense vector search + sparse full-text search → Reciprocal Rank Fusion → optional cross-encoder reranking
- Dense retrieval: pgvector stores 768-dimensional embeddings; HNSW supports approximate nearest-neighbor search with cosine distance.
- Sparse retrieval: PostgreSQL Full-Text Search uses GIN indexing for keyword-oriented matches.
- Rank fusion: Reciprocal Rank Fusion (RRF) combines dense and sparse rankings.
- Optional reranking: A cross-encoder may rerank candidates and can run locally or over HTTP. Local execution uses BAAI/bge-reranker-v2-m3 and may require a substantial model download.
- Generation boundary: The retrieval modules are not wired into the active LMS authoring workflow. That path uses raw PDF text extraction and prompt grounding instead.
The document-ingestion subsystem is implemented and exposed through the course-documents API. The hybrid search, RRF, and reranking modules exist in the codebase and support retrieval work, but they are not called by the active LMS authoring path. This distinction separates implemented engineering from current production integration.
Document processing
Document ingestion and retrieval are distinct backend subsystems. Course document uploads go through the course-documents API, where Docling provides layout-aware extraction, reading-order reconstruction, and table structure. Content is split with heading-aware HybridChunking, embedded, and stored as chunks and vectors in PostgreSQL with pgvector.
The active LMS authoring path has a different grounding mechanism: it extracts PDF text with pypdfium2 and injects that text into the generation prompt. It does not automatically pass uploaded PDFs through the full Docling, chunking, embedding, and hybrid-retrieval pipeline.
- 01Course-documents API
- 02PDF / document upload
- 03Docling layout processing
- 04Heading-aware HybridChunking
- 05Token-bounded chunks + heading paths
- 06Embedding generation
- 07PostgreSQL + pgvector
Exposed through /api/v1/courses/{course_id}/documents. This subsystem is separate from the raw pypdfium2 text grounding used by the active LMS authoring path.
The ingestion subsystem is implemented and exposed through the course-documents API. Its authoring integration is incomplete, which is different from saying the ingestion work itself is unimplemented.
Optional web research and citations
Tavily can provide external search results to the relevant generation workflow when web research is enabled. Research is opt-in, not automatically enabled for every request, and search caching is supported.
Where research-backed lesson citations are used, generated output uses numbered markers and a Sources bibliography. Citation validation checks whether markers correspond to available sources; this is not independent fact-checking of every statement, and citations are not guaranteed on every output.
Database and persistence
Primary relational store for users, courses, documents and versions, chunks and embeddings, generation runs and steps, course plan versions, authoring sessions, lesson versions, chat threads, and lesson proposals.
Stores 768-dimensional embeddings and supports vector similarity retrieval alongside relational data.
PostgreSQL-backed checkpoints persist workflow state and support agent-session resumption.
Supporting temporary state and coordination: generation/draft state, claims, login rate limiting, review counters, and LLM rate limiting. It is not the application source of truth.
Agent-session updates are delivered through in-memory SSE event storage. This is distinct from persisted LangGraph checkpoints; checkpoint persistence does not make the in-memory event stream shared across processes.
API and authentication
FastAPI exposes a REST API for health checks, identity, authoring, generation, review, and agent-session interactions.
/health · /health/ready/api/v1/auth/* · /api/v1/users/api/v1/author · /api/v1/generations · /api/v1/iterate · /api/v1/review/api/v1/drafts · /api/v1/courses/{course_id}/documents/api/v1/agent/sessions and session-specific subroutesOutline and answer interactions, revision, retry, approval, feedback, cancellationServer-Sent Events (SSE) for agent-session updatesAuthentication supports API keys for system integrations and JWT-based user authentication, delivered through HTTP-only session cookies or Bearer tokens. Passwords use Argon2id hashing.
Reliability and testing
Architecture tests enforce dependency boundaries; frozen API-contract tests protect compatibility; prompt snapshots help detect unintended prompt changes. Unit and contract tests cover backend behavior and API schemas. Ruff provides linting and formatting, and Docker supports reproducible deployment environments.
Testing approach
The repository includes automated tests, contract checks, and linting. This page does not publish a precise test count because the exact figure depends on the commit, selected test set, and environment.
Current Engineering Considerations
- The backend is designed around a single Uvicorn process; some background generation operations use in-process asynchronous tasks.
- Process-local tasks are not equivalent to a durable external job queue. Agent workflow checkpoints persist in PostgreSQL, while SSE event storage is currently in-memory and is not shared between multiple backend processes.
- Redis is optional supporting infrastructure, not a complete replacement for durable job processing. Multiple API replicas or workers should not be assumed safe without additional coordination.
- Document-processing and retrieval capabilities have integration boundaries that vary by execution route.
- A public deployment requires appropriate authentication, secret management, resource planning, rate limiting, and operational hardening.
Deployment topology
The intended topology keeps the frontend independent from the Python API service.
Communicates with CGS over its API.
Containerized service; configured application port 8100.
Persistent relational, vector, and graph-checkpoint storage.
Optional coordination, inference, research, and persistent document/model storage as configured.
Docker-based configuration and persistent storage requirements support deployment. This page describes the intended topology; it does not claim that this portfolio frontend or a public demo is deployed.
What makes CGS technically interesting
CGS is more than a single-prompt chatbot. Its course-agent workflow separates planning, writing, review, revision, and rendering; structured content contracts make outputs predictable; and the retrieval subsystem combines relational persistence with vector search. The retrieval design is implemented as a subsystem but is not yet wired into the active LMS authoring path. Optional external research and automated quality and API-contract tests round out a backend whose capabilities are exposed through an independently usable API.
Architecture Evolution: From Early RAG Design to the Current Backend
CGS has moved from exploring a separate vector-store architecture to consolidating application records, chunks, and embeddings in PostgreSQL. The statuses below distinguish deployed-in-repository implementation from earlier exploration and incomplete integration.
ChromaDB-based vector store
ChromaDB was an earlier design direction for storing document chunks with their embeddings and metadata, embedding a query, running semantic similarity search, and returning relevant context for downstream LLM generation. It is not an active dependency or runtime implementation in the current audited repository.
Current PostgreSQL-centered architecture
PostgreSQL 16 with pgvector is the current relational and vector foundation. It stores application data, document chunks, and 768-dimensional vectors together; HNSW supports vector search, while PostgreSQL full-text search provides the sparse path. RRF combines rankings and a cross-encoder can optionally rerank results. The design does not require a separate ChromaDB service.
Subsystem boundaries
Document parsing, chunking, embedding, hybrid retrieval, and reranking capabilities exist as backend subsystems, but their full pipeline is not integrated with the active LMS authoring path. Describing the subsystem does not imply that production authoring uses it.
Measure before changing the design
Candidate improvements—including chunking comparisons, retrieval evaluation, and stronger authoring integration—are experiments to validate, not completed features.
Embeddings, Vector Representations and Semantic Search
Implemented Text is transformed by an embedding model into a numerical vector. Semantically related passages should generally have nearby representations in the embedding space. During ingestion, document chunks are embedded and stored; during retrieval, the query is embedded and compared with those stored vectors.
Cosine similarity and distance
A query vector is compared with stored chunk vectors. The vector index finds nearby candidates and ranks them by similarity or distance; relevant chunks can enter generation context when the relevant retrieval path is integrated.
Cosine similarity measures the angle between vectors; cosine distance is used by the current pgvector search path. HNSW is the approximate nearest-neighbor indexing approach. Similarity values are rankings—not a claim of calibrated relevance or retrieval accuracy.
Document Ingestion: Turning Raw Documents into Searchable Knowledge
At a high level, ingestion transforms source files into retrievable passages. The actual stages depend on which backend path handles a document.
- 01Document upload or source acquisition
- 02PDF text extraction
- 03Document structure and layout analysis
- 04Text normalization
- 05Chunk creation
- 06Preserve metadata, heading path, and context
- 07Generate embeddings
- 08Store chunks, vectors, and metadata in PostgreSQL
- 09Make indexed content available for retrieval
Current ingestion components
- pypdfium2 supports the raw PDF text extraction used by the LMS authoring path.
- Docling supports OCR, reading-order reconstruction, layout-aware extraction, and table structure for course document ingestion.
- HybridChunking provides token-bounded, heading-aware chunking, with a configured maximum of approximately 512 tokens and preserved heading paths.
- Chunks and associated document metadata are persisted in PostgreSQL with pgvector for retrieval. The ingestion subsystem is implemented; its active LMS authoring integration is incomplete.
Chunking strategies and trade-offs
Splits text into consistent token or character lengths. It is simple to index, but may divide a sentence or concept across boundaries; larger chunks use more context tokens while smaller chunks increase index entries.
Repeats a configurable span between adjacent chunks to preserve boundary context. This can improve continuity, at the cost of duplicated storage, embedding work, and potentially redundant retrieved context.
Splits through a hierarchy such as sections, paragraphs, sentences, then smaller units. It tries to preserve natural structure while meeting size limits, but results depend on separator quality and document formatting.
Uses relationships between sentences or passages to choose boundaries, aiming to keep related ideas together. It may improve conceptual coherence but adds processing complexity and can be less predictable in chunk size.
Maintains relationships among documents, chapters, sections, and smaller chunks. It can return a precise passage with its broader context, but requires storing and resolving hierarchy metadata.
Combines document structure, semantic boundaries, and token limits. The current Docling HybridChunking path is described as token-bounded with a configured maximum of about 512 tokens and preserved heading paths. It is implemented in the document-ingestion subsystem but is not wired into the active LMS authoring workflow.
Only the token-aware Docling HybridChunking path described above is a current implementation. The other approaches are engineering options for comparison, not claims about the live pipeline.
Keyword Retrieval, BM25 and Hybrid Search
Implemented Vector similarity can miss exact technical terms, API names, product identifiers, rare keywords, numbers, and named entities. A lexical path can surface passages that match those terms directly.
BM25 is a common sparse ranking method. It balances query-term frequency in a document with inverse document frequency (rarer terms can carry more discriminative weight) and normalizes for document length. It often complements semantic search: vector retrieval can find paraphrases while lexical retrieval can favor exact terminology.
The current CGS sparse path uses PostgreSQL Full-Text Search with GIN and ts_rank_cd; it is not BM25. ChromaDB belongs to earlier exploration and is not the current primary vector store.
What CGS currently uses
The audited CGS sparse path uses PostgreSQL Full-Text Search with GIN indexing and ts_rank_cd ranking. This implementation is not BM25. BM25 is discussed here as a relevant alternative or proposed experiment, not as a current dependency or feature.
Current Hybrid Retrieval Architecture
Implemented The repository contains parallel dense and sparse retrieval paths combined with Reciprocal Rank Fusion; cross-encoder reranking is optional. The full retrieval flow is not wired into the active LMS authoring workflow.
ts_rank_cd rankingk = 60Hybrid retrieval modules exist in the repository but are not wired into the active LMS authoring workflow. The active authoring path uses raw PDF text grounding, not this full hybrid path.
Why combine the paths? Dense retrieval captures semantic similarity when wording differs; sparse retrieval captures lexical matches and precise terminology. RRF combines rankings without requiring their raw scores to be on the same scale.
RRF constant: k = 60. An optional BAAI/bge-reranker-v2-m3 cross-encoder evaluates query-candidate relevance more directly and can be configured for local or HTTP execution.
Proposed RAG Improvements and Engineering Experiments
Proposed These are possible experiments, not completed features or measured results. Evaluate them systematically against a representative corpus and relevance judgments rather than selecting settings by intuition.
- 01Compare fixed-size, recursive, semantic, and structure-aware chunking on the same document corpus.
- 02Evaluate chunk size and overlap combinations, including context preservation, token consumption, and index cost.
- 03Compare vector-only retrieval with sparse-only retrieval; compare PostgreSQL full-text ranking with a dedicated BM25 implementation.
- 04Compare embedding models and dimensions, and experiment with suitable distance metrics such as cosine and other supported alternatives.
- 05Tune HNSW indexing parameters and compare RRF with alternative rank-fusion approaches.
- 06Measure reranked and non-reranked retrieval, including the effect of a cross-encoder on ordering.
- 07Evaluate relevance with Recall@K, Precision@K, MRR, and nDCG; do not infer quality from intuition alone.
- 08Assess retrieved-context quality before it is sent to the LLM, including source coverage and redundancy.
- 09Add document-page-level source attribution and citation verification.
- 10Improve integration among document ingestion, retrieval, and the authoring workflow.
RAG Engineering Concepts and Technical Scope
A retrieval-augmented generation system spans a lifecycle: parse sources, create searchable units, index representations, retrieve and rank evidence, construct context, and evaluate the resulting evidence use.
Extract text and structure from source files, then normalize and store material so it can be searched.
Recover text and reading order from scanned or complex pages while retaining layout and table context where supported.
Prepare extracted text and split it into model-relevant units; token counts constrain chunk and prompt size.
Partition documents into retrievable passages, balancing precision, context preservation, token budget, and index cost.
Encode chunks and queries as numeric vectors whose geometric proximity can represent semantic relatedness.
Persist vectors and find nearby candidates; CGS uses pgvector with cosine-distance search in PostgreSQL.
Use a graph-based index to efficiently find likely nearby vectors without exhaustively comparing every stored vector.
Match query terms using lexical relevance. BM25 is a common term-based method; CGS currently uses PostgreSQL full-text search with ts_rank_cd, not BM25.
Build a searchable lexical representation and rank matching documents with PostgreSQL functions and indexes.
Combine independent ranked lists using rank positions so dense and sparse retrieval contribute to a shared ordering.
Score query and candidate text together to refine an initial result ordering; useful as an optional second stage.
Select and organize retrieved evidence for a generation prompt; grounding depends on the retrieval path actually being connected.
Use labeled relevance data and measures such as Recall@K, Precision@K, MRR, and nDCG to compare system choices.
Check that citation markers map to available sources; this validates references, not the factual correctness of every claim.
My Technical Contributions
My work was within an existing team codebase and alongside the broader system—not sole authorship of the complete CGS platform. The distinction below separates implementation work from collaborative contribution and team-owned architecture.
Implemented author normalization and filtering behavior, improving how author data was handled at the API and generation boundary.
Contributed to the structured content and rendering path, including AST-related handling and the conversion of structured lesson content into consumable HTML.
Contributed to authoring/generation API behavior and ownership handling so generation work remained associated with the correct author and request context.
Worked on prompt construction and validation behavior for structured generation, including failure handling and output-repair paths.
Contributed to LangGraph workflow behavior and the multi-stage lesson-generation pipeline, including state transitions and bounded revision behavior.
Contributed to optional web-research integration and the handling of research output in the generation workflow.
Contributed to document ingestion, chunking, embedding, dense and sparse retrieval, Reciprocal Rank Fusion, cross-encoder reranking, and retrieval evaluation. The ingestion subsystem is implemented and exposed through the course-documents API; the hybrid retrieval path is not yet wired into active LMS authoring.
AI Engineering Capabilities
These are areas where I have hands-on project exposure or am actively developing my skills. My experience is early-career, and depth varies across technologies.
LLM Applications and Agentic Systems
Multi-step AI workflows, graph-based orchestration, LLM API integrations, structured generation and validation, and workflow state and execution.
RAG and Information Retrieval
Document ingestion and extraction, chunking strategies, embeddings and semantic similarity, vector databases, dense and sparse retrieval, hybrid search, RRF, reranking, and grounded generation.
Backend Engineering
Python, FastAPI, PostgreSQL, SQLAlchemy, Pydantic, and REST APIs—applied through project work and ongoing learning.
Technical Walkthrough Available on Request
I can discuss the CGS architecture, technical decisions, and my individual contributions, and demonstrate authorized, sanitized code samples without exposing confidential company materials.
There is no public source repository or live CGS demo linked here.