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
• Decentralized Flux routing — Instance-local routing and signed peer manifests
• Feature-oriented architecture — Package layout and layering rules
• OpenAPI — Contract for the internal HTTP server in internal/api (health, prompt, nodes, aliases, analytics); /v1/chat/completions, /rerank and /ready are served but not yet in the spec. flux ships no binary that starts this server.

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        # Host contract, frozen engine-internal types
│   ├── DECENTRALIZED-FLUX.md          # Instance-local routing, signed peer manifests
│   └── FEATURE-MONOREPO.md            # Package layout and layering
├── design/
│   └── FLUX-ENTERPRISE.md             # Enterprise surfaces (design)
├── guides/
│   ├── CREDENTIAL-SETUP-FLOW.md
│   └── DYNAMIC-MODEL-DISCOVERY.md
└── plans/                             # Remediation plans and reviews

The HTTP contract lives outside this directory, at ../api/openapi.yaml. Retry/fallback, caching and routing strategies are described in ARCHITECTURE.md; there are no separate guides for them yet.

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
• Security: See SECURITY.md for vulnerability reporting