FrootAI Python SDK
Direct Python APIs for FrootAI knowledge, Solution Plays, FAI Protocol wiring, evaluation, and trusted federation.
Python product page · Setup guide · PyPI · API docs
Choose SDK or Python MCP
| Use | Choose |
|---|---|
| Application, service, notebook, evaluation job, or script needs direct Python return values | FrootAI Python SDK — this package |
| VS Code, Claude, Cursor, or another agent should call tools over Model Context Protocol | frootai-mcp |
The SDK is Python-standard-library based with zero runtime dependencies. Bundled knowledge and search work offline. Federation is lazy, but the current default client is deliberately transport-pending: applications must inject a supported transport before making live federation calls.
Five steps to first value
1. Install and verify
python -m pip install --upgrade frootai
frootai --version
Requirements: Python 3.10 or newer. Published classifiers cover Python 3.10–3.13.
2. Search bundled knowledge
from frootai import FrootAI
fai = FrootAI()
for result in fai.search("secure enterprise RAG", max_results=3):
print(result["id"], result["title"], result["score"])
module = fai.get_module("R2")
print(module["title"] if module else "Module not found")
Knowledge, glossary, Play metadata, and the BM25 search index are packaged with the wheel. No API key is required for these operations.
3. Inspect a Solution Play and cost direction
from frootai import FrootAI, SolutionPlay
fai = FrootAI()
play = SolutionPlay.get("01")
if play:
print(play.name, play.complexity)
estimate = fai.estimate_cost("01-enterprise-rag", scale="prod")
print(estimate)
Cost output is directional reference data, not a cloud bill or deployment quote. Confirm region, SKU, traffic, retention, and current provider pricing before committing spend.
4. Wire and validate the FAI Protocol
from frootai import FrootAI
fai = FrootAI()
manifest = fai.wire_play("01")
validation = fai.validate_manifest(manifest)
print(validation)
# Preview before creating a project structure
preview = fai.scaffold_play("01", project_name="customer-rag", dry_run=True)
print(preview)
The manifest connects knowledge, WAF context, agents, instructions, skills, hooks, and guardrails. Validation reports structure and references; it does not deploy infrastructure.
5. Evaluate quality or connect trusted tools
from frootai import Evaluator
scores = {
"groundedness": 4.6,
"relevance": 4.2,
"coherence": 4.4,
"fluency": 4.5,
}
evaluator = Evaluator()
print(evaluator.summary(scores))
print("passed:", evaluator.all_passed(scores))
Federation is optional and asynchronous. The current SDK exposes the client contract but does not silently start a kernel transport:
from frootai.federation import create_federation_client
# `transport` implements: async call({"method": str, "params": mapping})
mcp = create_federation_client(
transport=your_transport,
federation={
"pre_attach": ["azure"],
"trust_file": "/etc/frootai/trust.json",
"idle_disconnect_minutes": 30,
},
)
async def inspect_azure() -> None:
handle = await mcp.attach({"name": "azure", "trustOverride": True})
tools = await mcp.list_tools(handle)
print([tool["qualifiedName"] for tool in tools])
await mcp.detach(handle)
Without an injected transport, federation calls fail explicitly with kernel_connection_pending (or remote_mode_pending for the reserved remote mode). Review publisher evidence, credentials, tool annotations, and permissions before overriding a trust decision.
API map
FrootAI client
| Area | Methods |
|---|---|
| Knowledge | search, get_module, list_modules, list_layers, lookup_term, search_glossary |
| Solution Plays | estimate_cost, check_play_compatibility, get_learning_path |
| FAI Protocol | wire_play, validate_manifest, inspect_wiring, fai_protocol |
| Scaffolding | scaffold_play, list_templates |
| Architecture governance | get_waf_guidance, primitives_catalog |
| Federation | Lazy mcp client with discover, attach, list_tools, invoke, chain, and detach |
SolutionPlay catalog
from frootai import SolutionPlay
all_plays = SolutionPlay.all()
ready_plays = SolutionPlay.ready()
rag_plays = SolutionPlay.search("RAG")
play = SolutionPlay.get("01")
Use by_layer(...) to filter by FROOT layer. Readiness labels describe packaged metadata, not live cloud-state certification.
Evaluation
Evaluator supports configurable metrics and thresholds, check_thresholds, all_passed, summary, JSON output, and from_config.
Evaluation scores are caller-supplied unless your application integrates a scorer. The SDK does not claim that a model or deployment is safe solely because a dictionary passed local thresholds.
Lean primitive resolution
from frootai import resolve_primitive, fetch_primitive
resolved = resolve_primitive("fai-rag-architect", lean_mode=True)
content = fetch_primitive("fai-rag-architect", lean_mode=True)
Lean resolution prefers fidelity-verified compact variants and preserves an explicit full-content path when exact source is needed.
Advanced SDK modules: prompt experiments, Copilot patterns, and agentic loops
The wheel also includes callback-driven advanced modules:
| Module | Public pattern | Important boundary |
|---|---|---|
frootai.ab_testing |
PromptExperiment, PromptVariant, ExperimentResult |
The caller supplies the model and optional scorer callbacks |
frootai.copilot |
CopilotSession, retry/error/event helpers |
The default send implementation is a test placeholder; integrate a real provider by overriding _execute_send |
frootai.agentic_loop |
AgenticLoop, Task, LoopConfig, run_plan |
Uses disk state and optional validation commands; only run trusted commands in a controlled workspace |
Example prompt experiment:
from frootai.ab_testing import PromptExperiment, PromptVariant
experiment = PromptExperiment(
name="rag-prompt",
variants=[
PromptVariant("control", "Answer with citations."),
PromptVariant("concise", "Answer briefly and cite sources."),
],
)
results = experiment.run(
test_queries=["What is hybrid search?"],
model_fn=your_model_callback,
scorer_fn=your_scorer_callback,
)
print(experiment.summary(results))
These utilities are composition patterns, not bundled model access. The SDK never supplies provider credentials or production quality scores automatically.
Federation composition, errors, and forward compatibility
chain() performs SDK-side sequential composition over invoke(); there is no hidden fai_chain kernel operation. A chain is capped at 32 steps, and mapPrev can derive the next call's arguments from the previous result.
result = await mcp.chain([
{"tool": "azure.subscription_list", "args": {"tier": "verified"}},
{
"tool": "azure.resource_list",
"mapPrev": lambda previous: {"subscription": previous["id"]},
},
])
Canonical FederationError.code values are:
| Code | Meaning |
|---|---|
kernel_connection_pending |
No local kernel transport has been injected |
remote_mode_pending |
Reserved remote transport is not implemented in this release |
user_error |
Invalid caller arguments, handle, or tool name |
detach_failed |
The kernel explicitly rejected detach |
trust_blocked |
Trust policy refused the area |
tool_error |
The downstream tool failed |
transport_error |
Process or wire transport failed |
attach_timeout |
Attach did not complete within its deadline |
namespace_collision |
Attached areas exposed conflicting bare tool names |
Typed Tier-1 helpers are optional conveniences. Generic invoke("<area>.<tool>", args) remains the forward-compatible route for newly introduced tools.
Command-line reference
| Command | Purpose |
|---|---|
frootai plays [--layer LAYER] [--ready] |
Browse packaged Solution Plays |
frootai search <query> [--limit N] |
Search bundled knowledge |
frootai modules |
List FROOT modules |
frootai glossary [term] |
Browse or look up terminology |
frootai cost <play> [--scale dev|prod] |
Produce directional cost output |
frootai scaffold <play> [--name NAME] [--dry-run] |
Preview or create SDK scaffold output |
frootai wire <play> |
Generate a FAI manifest |
frootai validate <file> |
Validate a manifest file |
frootai evaluate metric=score ... |
Apply local evaluation thresholds |
frootai waf <pillar> |
Inspect Well-Architected guidance |
frootai primitives |
Show the packaged primitive catalog |
frootai learning-path <topic> |
Get a curated learning path |
Operating boundaries
| Boundary | Contract |
|---|---|
| Offline behavior | Bundled knowledge/search works without a network; live federation does not |
| Secrets | Pass tokens through application configuration or secret stores; do not log them |
| Cost | Estimates are static and directional |
| Scaffolding | Use dry_run=True before writing files |
| Federation | Trust gates, qualified tool names, bounded chains, and explicit detach preserve lifecycle visibility |
| Compatibility | New MCP tools can be invoked through generic invoke before typed helpers catch up |
Verify and develop
cd python-sdk
python -m pip install --upgrade build pytest
python -m pytest tests -v
python -m build
Related packages
| Package | Use it when |
|---|---|
frootai-mcp on PyPI |
An MCP client needs the Python tool server |
frootai-mcp on npm |
A Node.js MCP process or local federation router is preferred |
frootai on npm |
A terminal user needs Agent FAI and Operator CLI |
License
MIT © 2026 FrootAI.
Metadata
Release files for frootai 5.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| frootai-5.1.2.tar.gz | 557.9 kB | Without provenance | Details for frootai-5.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| frootai-5.1.2-py3-none-any.whl | Python 3 | none | any | Details for frootai-5.1.2-py3-none-any.whl |
Total release size: 1.1 MB
Release files / frootai-5.1.2.tar.gz
| Download URL | frootai-5.1.2.tar.gz |
|---|---|
| Size | 557.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b47026b627ed8c9439a3bf95e5f9d5a744707d81a691764476be55234ced4310
|
|
BLAKE2b-256 checksum How to use checksums |
66929d55f5fc2984160d22eff938747fc63d90c921aaf6149de1c5b7ad86e864
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / frootai-5.1.2-py3-none-any.whl
| Download URL | frootai-5.1.2-py3-none-any.whl |
|---|---|
| Size | 553.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f57c7697f1f66a229b01df2a493cf13df7b5c4bd8fb33f62d2a280b85ada772
|
|
BLAKE2b-256 checksum How to use checksums |
98299380064c80ec9f2de5c2e2e70a71dd8dfbdb9a143ee1c10b782cec8df38c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for frootai 5.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.