docs

Flux Documentation

Welcome to the Flux documentation. This directory contains detailed guides and reference material for the Universal LLM Provider Runtime.

Documentation Index

Core Documentation

• Architecture — System architecture, data flow, and design decisions
• Host-Engine Boundary — Stable engine/llm/graph/tools contract
• Flux Enterprise — Enterprise surfaces
• Provider Setup Guide — How to configure credentials and providers
• Dynamic Model Discovery — Architecture and implementation details for live model discovery
• OpenAPI — HTTP surface (/v1/chat/completions, /rerank, /ready, /health)

Quick Links

• README — Project overview and quick start
• Contributing Guide — How to contribute to Flux
• Security Policy — Security reporting and best practices
• Changelog — Version history and release notes

Examples

The examples/ directory contains runnable code samples:

• Basic Chat — Simple synchronous chat with a single provider
• Streaming — Server-sent events streaming with continuation
• Multi-Provider — Using fallback chains across multiple providers

Documentation Structure

docs/
├── README.md                          # This file
├── ARCHITECTURE.md                    # System architecture
├── architecture/HOST-ENGINE-BOUNDARY.md
├── design/FLUX-ENTERPRISE.md
├── api/openapi.yaml                   # POST /v1/chat/completions, POST /rerank, GET /ready
└── guides/
    ├── CREDENTIAL-SETUP-FLOW.md
    ├── DYNAMIC-MODEL-DISCOVERY.md
    ├── RETRY-FALLBACK.md              # (planned) backoff, fallback chains, circuit breaker
    ├── CACHING-AUDIT.md               # (planned) cache backends, audit sinks
    └── ROUTING-STRATEGIES.md          # weighted, latency, cost-based

For Developers

If you're contributing to Flux:

1. Read CONTRIBUTING.md for development setup
2. Review ARCHITECTURE.md to understand the system
3. Check AGENTS.md for AI agent context and conventions
4. Run make ci locally before submitting PRs

For Users

If you're using Flux in your application:

1. Start with the Quick Start in the main README
2. Review the Usage examples for common patterns
3. Check the examples/ directory for complete code samples
4. Read the Provider Setup Guide for credential configuration

API Reference

API documentation is available at:

• pkg.go.dev — Generated Go documentation
• ARCHITECTURE.md — Core abstractions and interfaces

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for vulnerability reporting