Crate fastapi_output 

Agent-aware rich console output for fastapi_rust.

This crate provides beautiful terminal output that automatically detects whether it’s running in an AI agent environment and switches to plain text mode accordingly.

Role In The System

fastapi-output is an optional, presentation-only layer. It formats diagnostics, route tables, middleware stacks, and test reports in a way that’s readable for humans and stable for automated agents. The main framework can run without it; the fastapi crate enables it by default behind a feature flag so production users can opt out.

Features

• Automatic agent detection (Claude Code, Codex, Cursor, etc.)
• Dual-mode output (Rich for humans, Plain for agents)
• FastAPI-themed color palette
• Tables, panels, progress bars, and more

Quick Start

use fastapi_output::prelude::*;

// Auto-detects mode based on environment
let output = RichOutput::auto();

// Print styled text (rendered appropriately for mode)
output.success("Server started successfully");
output.error("Failed to bind to port 8000");

// Check if running in agent-friendly mode
if output.is_agent_mode() {
    // Output is plain text, safe for agent parsing
}

Output Modes

The library supports three output modes:

Mode	Description	Use Case
Rich	Full ANSI styling with Unicode symbols	Human terminals
Plain	Zero ANSI codes, ASCII only	AI agents, CI, logs
Minimal	Colors only, no box characters	Simple terminals

Agent Detection

The library automatically detects agent environments by checking for known environment variables set by AI coding assistants:

Variable	Agent
CLAUDE_CODE	Claude Code CLI
CODEX_CLI	OpenAI Codex CLI
CURSOR_SESSION	Cursor IDE
AIDER_SESSION	Aider
AGENT_MODE	Generic agent flag
WINDSURF_SESSION	Windsurf
CLINE_SESSION	Cline
COPILOT_AGENT	GitHub Copilot agent mode

CI Detection

CI environments are also detected and default to plain mode:

Variable	CI System
CI	Generic CI flag
GITHUB_ACTIONS	GitHub Actions
GITLAB_CI	GitLab CI
JENKINS_URL	Jenkins
CIRCLECI	CircleCI
TRAVIS	Travis CI
BUILDKITE	Buildkite

Environment Variable Precedence

Environment variables are checked in the following order (highest to lowest priority):

1. FASTAPI_OUTPUT_MODE (highest) - Explicit mode selection

   • Values: rich, plain, minimal
   • Example: FASTAPI_OUTPUT_MODE=plain cargo run

2. FASTAPI_AGENT_MODE=1 - Force agent detection (plain mode)

   • Useful for testing agent behavior in a human terminal

3. FASTAPI_HUMAN_MODE=1 - Force human detection (rich mode)

   • Overrides agent detection when you want rich output

4. FORCE_COLOR - Standard force-color flag

   • Non-zero value forces rich output even in CI

5. NO_COLOR - Standard no-color flag

   • When set (any value), forces plain output

6. Auto-detection (lowest) - TTY check + agent/CI env vars

Precedence Examples

# Explicit mode always wins
FASTAPI_OUTPUT_MODE=rich CLAUDE_CODE=1 cargo run  # → Rich mode

# Agent override beats CI detection
FASTAPI_HUMAN_MODE=1 CI=true cargo run  # → Rich mode

# FORCE_COLOR beats NO_COLOR and CI
FORCE_COLOR=1 CI=true NO_COLOR=1 cargo run  # → Rich mode

# NO_COLOR beats auto-detection
NO_COLOR=1 cargo run  # → Plain mode (even in TTY)

For Agent Authors

If you’re building an AI coding agent that invokes fastapi_rust applications:

1. Set your agent’s env var (e.g., CLAUDE_CODE=1) for auto-detection
2. Or set FASTAPI_OUTPUT_MODE=plain for explicit plain mode
3. Parse plain output which uses consistent prefixes:
   • [OK] for success
   • [ERROR] for errors
   • [WARN] for warnings
   • [INFO] for info
   • [DEBUG] for debug

Components

The library provides several output components:

• Banner - Server startup banner with ASCII art
• RouteDisplay - Route table display
• ErrorFormatter - Validation and HTTP error formatting
• RequestLogger - HTTP request/response logging
• MiddlewareStackDisplay - Middleware stack visualization
• DependencyTreeDisplay - Dependency injection tree
• ShutdownProgressDisplay - Graceful shutdown progress
• TestReportDisplay - Test results formatting
• OpenApiDisplay - OpenAPI endpoint table and schema visualization (Phase 5)
• HelpDisplay - Help and usage display (Phase 5)

Re-exports

pub use detection::DetectionResult;

pub use detection::OutputPreference;

pub use detection::OverrideMode;

pub use detection::detect_environment;

pub use detection::detected_preference;

pub use detection::detection_diagnostics;

pub use detection::is_agent_environment;

pub use facade::RichOutput;

pub use facade::RichOutputBuilder;

pub use facade::StatusKind;

pub use facade::get_global;

pub use facade::set_global;

pub use mode::OutputMode;

pub use mode::feature_info;

pub use mode::has_rich_support;

pub use testing::OutputEntry;

pub use testing::OutputLevel;

pub use testing::TestOutput;

pub use testing::assert_contains;

pub use testing::assert_contains_in_order;

pub use testing::assert_has_ansi;

pub use testing::assert_max_width;

pub use testing::assert_no_ansi;

pub use testing::assert_not_contains;

pub use testing::capture;

pub use testing::capture_both;

pub use testing::capture_with_width;

pub use testing::debug_output;

pub use testing::is_verbose;

pub use testing::strip_ansi_codes;

pub use themes::FastApiTheme;

pub use themes::ThemePreset;

pub use components::banner::Banner;

pub use components::banner::BannerConfig;

pub use components::banner::ServerInfo;

pub use components::dependency_tree::DependencyNode;

pub use components::dependency_tree::DependencyTreeDisplay;

pub use components::errors::ErrorFormatter;

pub use components::errors::FormattedError;

pub use components::errors::HttpErrorInfo;

pub use components::errors::LocItem;

pub use components::errors::ValidationContext;

pub use components::errors::ValidationErrorDetail;

pub use components::help_display::ArgGroup;

pub use components::help_display::ArgInfo;

pub use components::help_display::CommandInfo;

pub use components::help_display::HelpDisplay;

pub use components::help_display::HelpInfo;

pub use components::http_inspector::RequestInfo;

pub use components::http_inspector::RequestInspector;

pub use components::http_inspector::ResponseInfo;

pub use components::http_inspector::ResponseInspector;

pub use components::logging::HttpMethod;

pub use components::logging::LogEntry;

pub use components::logging::RequestLogger;

pub use components::logging::ResponseTiming;

pub use components::middleware_stack::MiddlewareInfo;

pub use components::middleware_stack::MiddlewareStackDisplay;

pub use components::openapi_display::EndpointInfo;

pub use components::openapi_display::OpenApiDisplay;

pub use components::openapi_display::OpenApiDisplayConfig;

pub use components::openapi_display::OpenApiSummary;

pub use components::openapi_display::PropertyInfo;

pub use components::openapi_display::SchemaType;

pub use components::routes::RouteDisplay;

pub use components::routes::RouteEntry;

pub use components::routes::RouteTableConfig;

pub use components::routing_debug::CandidateRoute;

pub use components::routing_debug::ExtractedParams;

pub use components::routing_debug::MatchResult;

pub use components::routing_debug::RoutingDebug;

pub use components::routing_debug::RoutingDebugInfo;

pub use components::shutdown_progress::ShutdownPhase;

pub use components::shutdown_progress::ShutdownProgress;

pub use components::shutdown_progress::ShutdownProgressDisplay;

pub use components::test_results::TestCaseResult;

pub use components::test_results::TestModuleResult;

pub use components::test_results::TestReport;

pub use components::test_results::TestReportDisplay;

pub use components::test_results::TestStatus;

Modules

components

Core output components for fastapi_rust.

detection

Agent environment detection for output mode selection.

facade

Rich output facade.

mode

Output mode selection and switching.

prelude

Prelude module for convenient imports.

testing

Test utilities for output component testing.

themes

Theme system for fastapi_rust console output.

Macros

test_log

Log message if verbose mode is enabled.