Metadata-Version: 2.4
Name: frootai
Version: 5.1.0
Summary: FrootAI SDK — 101 solution plays, 863+ primitives, and a 62-tool Python MCP companion. Offline knowledge, BM25 search, FAI Protocol wiring, scaffold, evaluation, A/B testing, and CLI.
Author-email: Pavleen Bali <pavleenbali@frootai.dev>
License: MIT
Project-URL: Homepage, https://frootai.dev
Project-URL: Repository, https://github.com/frootai/frootai
Project-URL: Documentation, https://frootai.dev/api-docs
Keywords: frootai,ai,architecture,azure,mcp,agents,rag,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://frootai.dev/img/frootai-mark.png" width="100" alt="FrootAI">
</p>

<h1 align="center">FrootAI</h1>
<p align="center"><sub>Python SDK</sub></p>
<p align="center"><strong>From the Roots to the Fruits. It's simply Frootful.</strong></p>
<p align="center"><em>An open ecosystem where Infra, Platform, and App teams build AI — Frootfully.</em></p>
<p align="center"><em>A uniFAIng glue for the GenAI ecosystem, enabling deterministic and reliable AI solutions.</em></p>

<p align="center">
  <a href="https://pypi.org/project/frootai/"><img src="https://img.shields.io/pypi/v/frootai?style=flat-square&logo=python" alt="PyPI"></a>
  <a href="https://pypi.org/project/frootai/"><img src="https://img.shields.io/pypi/dm/frootai?style=flat-square&label=downloads" alt="downloads"></a>
  <a href="https://github.com/frootai/frootai/blob/main/LICENSE"><img src="https://img.shields.io/badge/MIT-yellow?style=flat-square&label=license" alt="license"></a>
</p>

---

### 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*.

<details>
<summary><strong>The FROOT Framework</strong></summary>
<br>

**FROOT** = **F**oundations · **R**easoning · **O**rchestration · **O**perations · **T**ransformation

| Layer | What You Learn |
|:-----:|---------------|
| **F** | Tokens, models, glossary, Agentic OS |
| **R** | Prompts, RAG, grounding, deterministic AI |
| **O** | Semantic Kernel, agents, MCP, tools |
| **O** | Azure AI Foundry, GPU infra, Copilot ecosystem |
| **T** | Fine-tuning, responsible AI, production patterns |

</details>

### The FAI Ecosystem

<p align="center">
  <img src="https://raw.githubusercontent.com/frootai/frootai/main/.github/fai-eco-big.png" width="700" alt="FAI Ecosystem — Factory builds, Packages deliver, Toolkit equips">
</p>

---

### Install

```bash
pip install frootai
```

### Quick Start

```python
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

```bash
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

| Feature | Description |
|---------|-------------|
| **BM25 Search** | Full-text search (358 docs × 8,627 terms), falls back to keyword |
| **Solution Plays** | Pre-architected Azure AI patterns with filtering |
| **FAI Protocol** | Wire, validate, inspect fai-manifest.json |
| **Scaffold** | Bootstrap projects with DevKit structure |
| **WAF Guidance** | 6-pillar Well-Architected Framework advice |
| **Evaluation** | Threshold-based quality gates with JSON export |
| **A/B Testing** | Prompt experiment framework with scoring |
| **Agentic Loop** | Ralph Loop — autonomous task execution |
| **Cost Estimation** | Itemized Azure cost estimates by play |
| **AI Glossary** | Comprehensive glossary extracted from knowledge modules |
| **CLI** | 13 commands for browsing, searching, scaffolding |
| **Zero Dependencies** | Pure Python stdlib, works anywhere |

### Testing

```bash
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

```python
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)

```python
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

```python
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:

```python
# 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):

| Code                          | Meaning                                                       |
| ----------------------------- | ------------------------------------------------------------- |
| `kernel_connection_pending`   | Wire transport not yet connected (PIN_ONE_AHEAD default)      |
| `user_error`                  | Invalid args / handle / tool name (caller bug)                |
| `detach_failed`               | Kernel explicitly reported `detached: False`                  |
| `trust_blocked`               | Trust gate refused; surfaces in `AttachHandle["blocked"]` (rarely raised) |
| `tool_error`                  | Underlying tool raised; payload in `humanMessage`             |
| `transport_error`             | Wire-level failure (process / I/O)                            |
| `attach_timeout`              | Kernel didn't ack attach within deadline                      |
| `namespace_collision`         | Two attached areas exposed the same bare tool name            |

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

---

### Links

| Resource | Link |
|---|---|
| **Website** | [frootai.dev](https://frootai.dev) |
| **Setup Guide** | [FAI Packages Setup](https://frootai.dev/setup-guide) |
| **Python MCP Server** | [PyPI — frootai-mcp](https://pypi.org/project/frootai-mcp/) |
| **Node MCP Server** | [npm — frootai-mcp](https://www.npmjs.com/package/frootai-mcp) |
| **VS Code Extension** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=frootai.frootai-vscode) |
| **Docker Image** | [GitHub Container Registry](https://github.com/frootai/frootai/pkgs/container/frootai-mcp) |
| **GitHub** | [frootai/frootai](https://github.com/frootai/frootai) |
| **Contact** | [info@frootai.dev](mailto:info@frootai.dev) |

---

<p align="center">© 2026 FrootAI — MIT License</p>
<p align="center"><sub>AI architecture · Python · SDK · Azure · RAG · agents · copilot · evaluation · cost-estimation · offline-first · zero-dependencies · open-source · frootai</sub></p>
