FrootAI

_{Python SDK}

From the Roots to the Fruits. It's simply Frootful.

An open ecosystem where Infra, Platform, and App teams build AI — Frootfully.

A uniFAIng glue for the GenAI ecosystem, enabling deterministic and reliable AI solutions.

The Philosophy Behind FrootAI — The Essence of the FAI Engine

FrootAI is an intelligent way of packaging skills, knowledge, and the essential components of the GenAI ecosystem — all synced, not standalone. Infrastructure, platform, and application layers are woven together so that every piece understands and builds on the others. That's what "from the roots to the fruits" means: a fully connected ecosystem where Infra, Platform, and App teams build AI — Frootfully.

The FAI Ecosystem

Install

pip install frootai

Quick Start

from frootai import FrootAI, SolutionPlay, Evaluator

client = FrootAI()

# Search knowledge
results = client.search("RAG architecture")

# Get a module
module = client.get_module("R2")  # RAG Architecture

# Browse solution plays
plays = SolutionPlay.all()

# Estimate Azure costs
cost = client.estimate_cost("01-enterprise-rag", scale="prod")

# Run evaluation
evaluator = Evaluator()
scores = {"groundedness": 4.5, "relevance": 3.8}
results = evaluator.check_thresholds(scores)

CLI

frootai plays                    # List all solution plays
frootai search "embeddings"      # BM25 search across knowledge
frootai modules                  # List FROOT modules
frootai glossary temperature     # Look up a term
frootai cost 01-enterprise-rag   # Azure cost estimate
frootai scaffold 01 --dry-run    # Preview scaffold output
frootai wire 01                  # Generate fai-manifest.json
frootai validate manifest.json   # Validate FAI manifest
frootai evaluate groundedness=4.5 relevance=3.8  # Run quality check
frootai waf security             # WAF pillar guidance
frootai primitives               # Browse AI primitives
frootai learning-path rag        # Curated learning path

Features

Testing

pip install pytest
python -m pytest tests/ -v
# 123 tests

Federation

The SDK ships an asyncio-based FederationClient that wraps the FAI MCP federation kernel — discover marketplace areas, attach a trusted area, list its tools, invoke them, and detach when done. The client is lazy (importing FrootAI does not spawn a kernel subprocess) and offline-first (every method dispatches through an injectable transport so unit tests can drive the client without a live kernel). The Python public surface is byte-for-byte parity with the npm-sdk twin (snake_case method names per PEP 8; the cross-language scripts/sdk-parity-check.mjs enforces drift detection in CI).

Constructor opts

from frootai import FrootAI

fai = FrootAI(
    federation={
        "pre_attach": ["azure", "playwright"],         # areas to pre-attach on kernel spawn
        "trust_file": "/etc/frootai/trust.json",       # path to the trust manifest
        "idle_disconnect_minutes": 30,                  # auto-detach after N minutes idle (1..1440)
    },
)

mcp = fai.mcp  # lazy — kernel transport spins up on first access

attach → list_tools → invoke → detach (canonical flow)

import asyncio
from frootai import FrootAI
from frootai.federation import FederationError

async def main() -> None:
    fai = FrootAI(federation={"pre_attach": ["azure"]})
    mcp = fai.mcp
    try:
        handle = await mcp.attach({"name": "azure", "trustOverride": True})
        if handle.get("blocked"):
            print(f"trust gate refused: {handle.get('humanMessage')}")
            return

        tools = await mcp.list_tools(handle)
        for tool in tools:
            print(tool["qualifiedName"], tool.get("description"))

        result = await mcp.invoke("azure.list_subscriptions", {"tier": "verified"})
        print(result)

        await mcp.detach(handle)  # resolves None; raises FederationError on explicit kernel failure
    except FederationError as e:
        if e.code == FederationError.ATTACH_TIMEOUT:
            # canonical UPPER_SNAKE class attributes cover the 8-code taxonomy
            print("attach timed out")
        raise

asyncio.run(main())

chain — sequential federated calls with prev-mapping

final_result = await mcp.chain([
    {"tool": "azure.list_subs", "args": {"tier": "verified"}},
    {"tool": "azure.list_vms",  "mapPrev": lambda prev: {"subId": prev["id"]}},
    {"tool": "azure.show_vm",   "mapPrev": lambda prev: {"vmName": prev["name"]}},
])

chain() is SDK-side composition over invoke() — there is no fai_chain kernel method. Each step dispatches as a regular fai_invoke_tool round-trip; mapPrev extracts the previous step's result into the next step's args. Capped at 32 steps (MAX_CHAIN_STEPS).

Forward-compatibility: typed helpers are OPTIONAL

The Tier-1 typed helpers (build_tier1_accessors(client), e.g. tier1.azure.subscription_list(args)) are an ergonomic layer on top of invoke(). They are NEVER required:

# Forward-compatible direct invocation — works for ANY tool the
# kernel exposes, including ones not yet in the typed-helper
# snapshot (or kernel-only tools that intentionally bypass the
# typed surface).
result = await mcp.invoke("azure.subscription_list", {"tier": "verified"})
new_area_result = await mcp.invoke("future_area.future_tool", { ... })

The canonical wire-literal is the snake_case <area>.<tool> form. The typed helpers exist purely for IDE autocomplete + compile-time-checkable args; consumers who add a NEW federated area do NOT have to wait for a typed-helper codegen pass before invoking it. This keeps the SDK forward-compatible with kernel-side tool additions and Tier-2/3 areas that will never get bespoke wrappers.

Error taxonomy

FederationError.code is one of 8 canonical codes (byte-for-byte mirrored from the npm-sdk twin):

For static type-checking, import the codegen-emitted FederationErrorCode Literal alias from frootai.federation.types.

Links

© 2026 FrootAI — MIT License

_{AI architecture · Python · SDK · Azure · RAG · agents · copilot · evaluation · cost-estimation · offline-first · zero-dependencies · open-source · frootai}