FAI Configuration Guide

One manifest replaces scattered .github/ configs — DevKit, TuneKit, SpecKit explained.

L3·14 min read·High

The Three Kits

FrootAI organizes configuration into three distinct kits, each owning a different aspect of an AI solution play. Together they replace the scattered, ad-hoc config files that plague most AI projects.

Kit	Location	Owns	Files
DevKit	`.github/`	Runtime primitives	agents/, instructions/, skills/, hooks/, workflows/
TuneKit	`config/`	Quality configuration	openai.json, guardrails.json, agents.json
SpecKit	`spec/`	Wiring specification	play-spec.json, architecture decisions

DevKit — The .github/ Directory

DevKit holds all runtime primitives that shape Copilot's behavior. These files are active in your editor — Copilot reads them automatically when you open a project.

.github/ directory structure

.github/
├── copilot-instructions.md          # Global project-level instructions
├── agents/
│   ├── fai-rag-architect.agent.md
│   ├── fai-code-reviewer.agent.md
│   └── fai-azure-openai-expert.agent.md
├── instructions/
│   ├── python-waf.instructions.md   # applyTo: **/*.py
│   ├── bicep-waf.instructions.md    # applyTo: **/*.bicep
│   └── typescript-waf.instructions.md
├── skills/
│   ├── fai-play-initializer/
│   │   └── SKILL.md
│   └── deploy-01-enterprise-rag/
│       ├── SKILL.md
│       └── templates/
├── hooks/
│   └── fai-secrets-scanner/
│       ├── hooks.json
│       └── scan-secrets.js
└── prompts/
    └── rag-query.prompt.md

TuneKit — The config/ Directory

TuneKit controls model behavior, safety guardrails, and agent routing. These JSON files define the quality dial settings that determine how your AI solution performs in development, staging, and production.

openai.json — Model Configuration

Controls the LLM call parameters. Every solution play ships with a pre-tuned openai.json optimized for its use case. The FAI Engine validates these values against known-good ranges.

config/openai.json

{
  "model": "gpt-4o",
  "temperature": 0.1,
  "max_tokens": 1000,
  "top_p": 0.95,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "seed": 42,
  "response_format": { "type": "text" },
  "stop": null
}

Parameter	Range	RAG Default	Why
temperature	0.0–2.0	0.1	Low for factual grounding
max_tokens	1–128000	1000	Budget-safe for most queries
top_p	0.0–1.0	0.95	Nucleus sampling breadth
seed	integer	42	Deterministic outputs for eval

guardrails.json — Safety Configuration

Defines content safety thresholds, PII detection rules, prompt injection blocking, and business-specific constraints. Every primitive in the play respects these guardrails.

config/guardrails.json

{
  "content_safety": {
    "enabled": true,
    "categories": {
      "hate": { "severity": "medium", "action": "block" },
      "sexual": { "severity": "medium", "action": "block" },
      "violence": { "severity": "medium", "action": "block" },
      "self_harm": { "severity": "medium", "action": "block" }
    }
  },
  "pii_detection": {
    "enabled": true,
    "action": "redact",
    "entities": ["email", "phone", "ssn", "credit_card"]
  },
  "prompt_injection": {
    "enabled": true,
    "action": "block"
  },
  "evaluation_thresholds": {
    "groundedness": 0.85,
    "relevance": 0.80,
    "coherence": 0.90,
    "fluency": 0.85,
    "safety": 0.95
  }
}

agents.json — Agent Routing

Defines model routing rules for multi-agent plays. Route simple queries to smaller, cheaper models and complex queries to full-capacity models — the key to cost optimization in agentic systems.

config/agents.json

{
  "routing": {
    "default_model": "gpt-4o-mini",
    "rules": [
      {
        "pattern": "architecture|design|security",
        "model": "gpt-4o",
        "max_tokens": 2000
      },
      {
        "pattern": "summarize|format|list",
        "model": "gpt-4o-mini",
        "max_tokens": 500
      }
    ]
  }
}

SpecKit — The spec/ Directory

SpecKit holds the wiring specification and architecture decision records. The play-spec.jsonsummarizes the play's architecture choices, target Azure services, and scaling parameters.

spec/play-spec.json (excerpt)

{
  "play": "01-enterprise-rag",
  "architecture": "retrieval-augmented-generation",
  "index_strategy": "hybrid-search",
  "embedding_model": "text-embedding-3-large",
  "chunk_size": 512,
  "chunk_overlap": 128,
  "reranker": "semantic-ranker",
  "deployment": {
    "compute": "azure-container-apps",
    "region": "eastus2",
    "sku": "consumption"
  }
}

Configuration Inheritance Chain

FrootAI uses a three-level inheritance chain. More specific configurations override less specific ones:

Inheritance order (lowest → highest priority)

Level 1: fai-manifest.json    # Play-wide defaults
  ↓ overrides
Level 2: config/*.json         # Kit-specific tuning
  ↓ overrides
Level 3: primitive frontmatter # Per-primitive settings

# Example: temperature
# Manifest sets context.waf (no temperature)
# config/openai.json sets temperature: 0.1
# Agent frontmatter can override with its own model config
# A creative-writing agent could set temperature: 0.8

Environment-Specific Overrides

For multi-environment deployments, create environment-specific config files. The FAI Engine selects the right one based on the FAI_ENV environment variable:

Environment config structure

config/
├── openai.json              # Default (development)
├── openai.staging.json      # Staging overrides
├── openai.production.json   # Production overrides
├── guardrails.json          # Default guardrails
└── guardrails.production.json  # Stricter production safety

# Usage:
FAI_ENV=production node engine/index.js fai-manifest.json
# → Loads openai.production.json + guardrails.production.json

Validating Configuration

Always validate your configuration before deploying. The validation script checks JSON syntax, schema compliance, and cross-references between manifest and config files:

Terminal

# Validate all primitives and configs
npm run validate:primitives

# Check consistency across all files
npm run validate:consistency

# Full build pipeline (validate → generate → sync)
npm run build

L2: How Context Wiring Works

L4: Instructions Authoring

L2: How Context Wiring Works L1: FAI Primitive Primer

Learning Hub Back to FrootAI