Home

FML (Frags Modeling Language) Wiki

Welcome to the official documentation for FML (Frags Modeling Language).

FML is a domain-specific orchestration language designed for building robust, multi-stage AI agent workflows. It provides a formal syntax to define structured prompts, deterministic tool integrations, complex data transformations, and strictly typed JSON outputs—optimized for frontier models such as Gemini 3 Pro.

FML has been designed to instruct the Frags Engine, but you're welcome to use it for your projects.

graph LR
    subgraph Global["Global Scope"]
        P[Parameters]
        R[Require Tools]
        C[Components]
        GCall[Global PreCalls]
    end

    subgraph Sessions["Sequential & Parallel Sessions"]
        S1["Session: Ingestion<br/>(Phase 1 PreCalls + Phase 2 Pre-Prompts)"]
        S2["Session: Transformation<br/>(Phase 2 Pre-Prompts + Phase 3 Prompts)"]
        S3["Session: Synthesis<br/>(Schema Validation & context Publish)"]
    end

    subgraph Output["Context Namespace"]
        CTX[("context.<session_name>")]
    end

    Global --> S1
    S1 -->|context| S2
    S2 -->|context| S3
    S3 --> CTX

Loading

---

Key Capabilities

• Phased Session Lifecycle: Enforces a hard architectural boundary between Context Enrichment (where the LLM freely uses tools via + pre-prompts) and Final Structuring (where tool access is disabled so the LLM focuses purely on generating valid JSON via - prompts).
• Dual Expression Engines:
  • Go text/template for high-speed string interpolation with standard dot-syntax and custom filters like | json.
  • Antonmedv expr for typed, non-string evaluations inside call arguments ($(...)), condition expressions (expect="..."), and iterative loops (iterate="...").
• Deterministic PreCalls: Run synchronous tool executions or sandboxed JavaScript routines (both completion-value notation and full IIFEs) before the model begins reasoning.
• Isolated Namespaces: Clean isolation between input parameters (params), intermediate runtime variables (vars), completed session outputs (context), and iteration items (it).
• Strict Schema Enforcement: Flat schemas, component references ($ComponentName), typed arrays, and union/enum declarations ensure guaranteed JSON responses.

---

Complete "Hello World" Plan

Here is a complete FML plan demonstrating global configuration, session dependency chaining, tool calls, and structured schema outputs:

# Global system prompt applied to all sessions
system(`You are an expert market research assistant.
Always provide factual, well-structured summaries.`)

# Global input parameter declaration
parameter("topic", type="string", default="quantum computing")
parameter("max_results", type="int", default=3)

# External MCP tool dependency
require mcp search_engine

# Reusable schema component
components {
    schema("ResourceItem") {
        title: string       # Article or resource title
        url: string         # Web address
        relevance: low|medium|high # Evaluated relevance
    }
}

# Session 1: Research & Information Gathering
session("gather_research", target="research_data") {
    use mcp search_engine { allowlist = ["search", "summarize"] }

    # Phase 2: Pre-prompt (LLM can invoke tools declared above)
    + Search for the latest breakthroughs regarding {{ .params.topic }}.
      Retrieve at least {{ .params.max_results }} relevant sources.

    # Phase 3: Prompt (Tool use is disabled; focus on JSON mapping)
    - Consolidate the findings into the requested structure.

    # Phase 4: Validated against schema
    schema {
        topic: string
        summary: string
        resources: $ResourceItem[]
    }
}

# Session 2: Executive Brief Generation (Depends on Session 1)
session("generate_brief", after="gather_research") {
    context "Research Material: {{ .context.research_data | json }}"

    - Create an executive bulleted brief based strictly on the research material.

    schema {
        headline: string
        key_takeaways: string[]
        recommended_action: string
    }
}

---

Wiki Documentation Roadmap

Explore the comprehensive guides below to learn FML from syntax fundamentals to advanced architectural patterns:

Section	Description
Getting Started	Installation, runtime expectations, execution model, and your first step-by-step FML plan.
Language Overview	Syntax philosophy, file anatomy, lexical conventions, comments, and top-level structure.
Cheat Sheet	High-density syntax quick reference, tables, and code snippets.
File-Level Constructs	Deep dive into system, parameter, set, require, transformer, components, and global call.
Sessions & Lifecycle	The 4-phase execution lifecycle, pre-prompts (+) vs. prompt (-), after, expect, iterate, and target.
Variables & Namespaces	The 4 isolated scopes (params, vars, context, it), shadowing rules, and scope resolution.
Expression Systems	Go Templates ({{ ... }}) vs. Antonmedv expr ($( ... )), operators, filters, and native type preservation.
Calls & PreCalls	Deterministic tool calling, embedded JavaScript execution (code(...)), and target namespace routing (-> vars:x).
Tools & Integrations	Integrating MCP servers, database collections, the built-in search tool, and data transformers.
Schemas & Components	Defining structured outputs, primitive and complex types, enum unions (a|b|c), and reusable components.
Architectural Patterns	Production patterns: Data Piping, Token Optimization, Deterministic Bypassing, and Tool-Free Chain of Thought.
Compiler & Validation Rules	Compiler constraints, anti-patterns to avoid, validation checks, and debugging tips.
Examples & Cookbook	End-to-end real-world reference plans with line-by-line architectural breakdowns.

---

Tip

New to FML? Start with the Getting Started guide, then check out Sessions & Lifecycle to understand how FML manages LLM execution.