Skip to content

Guides

These guides provide in-depth documentation on Functualize's core systems and features. Each guide covers a specific topic with explanations, configuration details, and code examples to help you get the most out of the framework.

Whether you're configuring layered settings, building auto-discovered jobs, extending the framework with plugins, building AI-powered workflows, or creating custom Domain SDKs, you'll find detailed coverage here.

Topics

  • Usage Modes — Single-file, directory, library, and adapter modes — when to use each, how to scaffold, and feature comparison
  • Architecture — Boot sequence, three-layer job pipeline, config resolution, interactivity layer, and extension points overview
  • Configuration System — Layered TOML configuration with environment overlays, upward directory search, per-job sections, and credentials declared with Secret[str]
  • Jobs and Auto-Discovery — How jobs are discovered via pkgutil, registered as CLI commands, and grouped into sub-commands
  • Subjects — When a job module should be a class: the subject test, the three axes (substrate / actions / target), and how subject classes bind via a plugin
  • JobConfig with Pydantic — Declarative, typed job configuration with automatic CLI option generation, multi-source resolution, and the JOB_FIELD environment convention
  • RunContext Lifecycle — Lifecycle hooks for setup, teardown, and error handling with metadata tracking and workflow steps
  • Domain SDKs — Lightweight capability packages (AI, State, Tasks, Interactivity) with protocols, types, and testing doubles
  • AI Capability — LLM interaction (complete, run, stream, extract), ToolScope restrictions, budget enforcement, and MockAI testing
  • Workflows — Declarative multi-step job graphs with @workflow, conditional branching, gates, and scope tracking
  • Shell Capability — Run external commands with lifecycle management, secret redaction, context managers, and FakeShell testing
  • Task Runner — @job decorator with dependencies, fingerprint caching, guard pipeline, parallel execution, and pipeline mode
  • Composing Capabilities — how the guides above fit together: use cases, a combination matrix of what happens at each intersection, an idiomatic matrix of what you lose by hand-rolling, and the five traps between features. Every claim is executed by examples/standalone/composition_lab/
  • MCP Adapter — Expose jobs as MCP tools for external AI agents, schema export, multi-server management
  • Plugins — Extending Functualize with entry-point-based plugins and the PluginMetadata protocol
  • Interactivity — the Surface and PromptCollector protocols, the TTY and Live job capabilities, rc.prompts.ask(), and rc.events.emit()
  • TUI Integration — Interactive terminal interfaces: the inline SmartBar TUI (auto-generated from job metadata) and Textual full-screen applications
  • Hooks — Cross-cutting lifecycle hook system with global and job-scoped registration, PRE_EXECUTE gating, and signature-adaptive dispatch
  • Hooks vs Plugins — When to use hooks vs plugins, and how to share reusable behavior with colleagues
  • Hierarchical Projects — Flat and hierarchical job composition with parent-child project relationships
  • Hierarchy Validation — Version compatibility checking and cycle detection for hierarchical project structures