Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
deploy
deploy
 
 
superpowers
superpowers
 
 
README.md
README.md
 
 
agents.md
agents.md
 
 
architecture.md
architecture.md
 
 
comparison-vs-qmd.md
comparison-vs-qmd.md
 
 
content.md
content.md
 
 
embeddings.md
embeddings.md
 
 
experiments.md
experiments.md
 
 
explainability.md
explainability.md
 
 
exposure-queues.md
exposure-queues.md
 
 
exposure-rest.md
exposure-rest.md
 
 
lab.md
lab.md
 
 
memory.md
memory.md
 
 
observability.md
observability.md
 
 
pipeline.md
pipeline.md
 
 
prompts.md
prompts.md
 
 
reasoning.md
reasoning.md
 
 
security.md
security.md
 
 
templates.md
templates.md
 
 
tools.md
tools.md
 
 
tutorial.md
tutorial.md
 
 
use-case-corpus-search.md
use-case-corpus-search.md
 
 
use-case-idp.md
use-case-idp.md
 
 
validation.md
validation.md
 
 
vectorstores.md
vectorstores.md
 
 

README.md

fireflyframework-agentic — Documentation

Python 3.13+ License: Apache 2.0 Version

Copyright 2026 Firefly Software Foundation. Licensed under the Apache License 2.0.

fireflyframework-agentic is the production-grade GenAI metaframework built on Pydantic AI. It extends the engine with six composable layers — from core configuration through agent management, intelligent reasoning, experimentation, pipeline orchestration, and service exposure — so that every concern has a dedicated, protocol-driven module.

Getting Started

  • Installation — Install via uv add, pip install, or the interactive installer scripts (install.sh / install.ps1).
  • Quick Start — Configure a provider, define an agent, register a tool, and run your first prompt in 5 minutes.
  • The Complete Tutorial — A 20-chapter, hands-on guide covering every concept from zero to expert through a real-world IDP pipeline.

Documentation Map

The framework is organised into six layers. Each layer depends only on the layers below it, keeping the dependency graph acyclic and each module independently testable.

Core Layer
Architecture Design principles, six-layer model, protocol hierarchy, dependency flow

Agent Layer
Agents FireflyAgent, AgentRegistry, AgentLifecycle, delegation, @firefly_agent decorator
Template Agents Five factory functions: summarizer, classifier, extractor, conversational, router
Tools ToolProtocol, ToolBuilder, guards, composition patterns, 9 built-in tools
Prompts PromptTemplate, PromptRegistry, composers, validation, loaders
Content TextChunker, DocumentSplitter, ImageTiler, BatchProcessor, compression
Memory ConversationMemory, WorkingMemory, MemoryManager, storage backends

Embeddings & Vector Stores
Embeddings BaseEmbedder, 8 providers (OpenAI, Azure, Cohere, Google, Mistral, Voyage, Bedrock, Ollama), auto-batching, similarity utilities, EmbedderRegistry
Vector Stores BaseVectorStore, 4 backends (In-Memory, ChromaDB, Pinecone, Qdrant), auto-embedding, search_text, namespaces, VectorStoreRegistry

Intelligence Layer
Reasoning Patterns 6 patterns (ReAct, CoT, Plan-and-Execute, Reflexion, ToT, Goal Decomposition), pipeline
Validation & QoS Rules, OutputValidator, OutputReviewer, confidence/consistency/grounding checks

Security
Security PromptGuard (27 patterns), OutputGuard (PII, secrets, harmful), PromptGuardResult, OutputGuardResult, injection detection, input sanitisation, output scanning

Observability
Observability FireflyTracer, FireflyMetrics, FireflyEvents, UsageTracker, CostCalculator, @traced, @metered, JsonFormatter, exporters
Explainability TraceRecorder, ExplanationGenerator, AuditTrail, ReportBuilder

Experimentation Layer
Experiments Experiment, Variant, ExperimentRunner, ExperimentTracker, VariantComparator
Lab LabSession, Benchmark, EvalOrchestrator, EvalDataset, ModelComparison

Orchestration Layer
Pipeline DAG, PipelineEngine, PipelineBuilder, step types, parallel execution, retries

Exposure Layer
REST Exposure create_agentic_app(), auto-generated routes, SSE streaming, WebSocket, auth middleware, conversation CRUD, rate limiting, health checks
Queue Exposure Kafka, RabbitMQ, Redis consumers/producers, QueueRouter

Studio

Studio (visual IDE, project API, scheduling, tunnel exposure, BPM tutorial) lives in a separate repository: fireflyframework-agentic-studio.

Tutorial

The Complete Tutorial is a 20-chapter, hands-on guide that teaches every concept from zero to expert through a real-world Intelligent Document Processing pipeline. It covers configuration, agents, tools, prompts, reasoning, content processing, memory, validation, pipelines, observability, explainability, experiments, lab, REST and queue exposure, deployment, and advanced patterns.

Use Cases

  • IDP Pipeline — A focused walkthrough of building a 7-phase Intelligent Document Processing pipeline that ingests, splits, classifies, extracts, validates, assembles, and explains data from corporate documents — including LLM-powered document splitting and explainability.

Contributing

See the Contributing Guide for development setup, coding standards, testing, and the pull request process.

Additional Resources

Copyright 2026 Firefly Software Foundation. Licensed under the Apache License 2.0.