Writing Agent
An Auditable, Self-Correcting Agentic Writing Assistant
The Writing Agent is an advanced, production-minded text processing application that replaces traditional “one-shot” LLM prompts with a robust, multi-step agent loop. Rather than blindly returning a generated string, the system plans the objective, drafts the content, scores it against a strict rubric, and runs a self-correction pass if quality thresholds are missed.
Applying rigorous architectural design and future-forward standards, the application is structured to ensure that text transformation—whether condensing, rewriting, or shifting tone—is verifiable, safe, and highly observable.
The Architectural Problem
Most AI writing tools behave like opaque one-offs. They rewrite once, offering no guarantees regarding clarity, faithfulness to the source text, or tone adherence. This black-box approach is unreliable and risky for high-stakes business communication.
The Solution's Core Value
Built a compact, deterministic agent loop that plans, drafts, scores, and self-corrects. By separating the Planner, Editor, Critic, and Fixer into distinct domain services, the system guarantees auditable rewrites with integrated evaluation and guardrails.
Technical Architecture and Production Features
The core infrastructure is built around a scalable FastAPI backend, emphasizing systemic reliability, clean domain separation, and deep observability.
Agent Core & Reasoning
The Agentic Pipeline
A structured workflow for verifiable output.
- Domain-Driven Pipeline: Execution flows through clearly separated domain logic:
Planner$\rightarrow$Editor$\rightarrow$Critic$\rightarrow$Fixer$\rightarrow$Polish. - Automated Self-Correction: The
Criticservice evaluates the draft against a rubric (Clarity, Faithfulness, Tone, Length). If it fails or exhibits toxicity, theFixerexecutes a targeted correction pass before yielding the result. - Pluggable LLM Backends: Uses an abstraction layer allowing seamless switching between local models (Ollama), OpenAI, Anthropic, or heuristic mock endpoints.
System Integrity & Guardrails
Production-Grade FastAPI
Resilient infrastructure built for scale.
- Resource Protection: Implements strict safeguards including per-IP in-memory rate limiting, payload size caps (
MAX_BODY_BYTES), and streaming duration timeouts. - Unified Error Handling: All application exceptions are caught and standardized into a predictable error envelope (
{code, message}), preventing infrastructure leakage. - Toxicity & Term Coverage: Enforces strict compliance checks ensuring all mandatory “must-keep” terms are preserved and explicitly blocking predefined toxic terminology.
Operational UX & MLOps
Observability & Control
Transparent operations for developers and users.
- Granular Tone Control: Exposes continuous “Human Knobs” (warmth, directness, hedging) and boolean “Switches” (no fluff, inclusive language) via dynamic preset resolution.
- Deep Traceability: Every agent step generates local NDJSON traces tied to an
X-Request-Id, capturing the delta between the baseline score and the final output. - Built-in Metrics: Exposes
GET /health,GET /ready, andGET /metricsendpoints, tracking request volumes, latency buckets, and toxicity failure rates.
Repository Layout: An Architecture of Clarity
The codebase isolates side effects and web transport logic from the core agentic reasoning, enabling high testability and future modularity:
src/writing_agent/
├── api/ # FastAPI transport, schemas, middleware, and rate-limiting
├── app/ # Application orchestration (Pipeline flow, Tone Merger)
├── domain/ # Core business logic (Planner, Editor, Critic, Fixer, Polish)
├── infra/ # External state, LLM adapters, metrics, tracing, and config
├── assets/ # Tone presets, audience mappings, and toxicity rules
└── cli/ # Local developer tools and utilities
web/ # Vanilla JS/HTML/CSS static frontend and visualizationsThis clear organization is fundamental to building scalable and auditable AI systems.