Metadata-Version: 2.5
Name: faf-python-sdk
Version: 2.0.0
Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
Project-URL: Homepage, https://faf.one
Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
Project-URL: Repository, https://github.com/Wolfe-Jam/faf-python-sdk
Project-URL: Issues, https://github.com/Wolfe-Jam/faf-python-sdk/issues
Author-email: wolfejam <wolfejam@faf.one>
License: MIT
License-File: LICENSE
Keywords: ai-context,claude,faf,grok,mcp,project-context,yaml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.8
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# faf-python-sdk

**Persistent Project Context for Python. Parse, validate, score.**

**FAF defines. MD instructs. AI codes.**

The foundation other Python FAF tools build on. If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.

[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
[![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
[![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
[![Tests](https://img.shields.io/badge/tests-1070%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
[![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)

**Media Type:** `application/vnd.faf+yaml` (IANA registered)

## What's New in v2.0.0 — The Always33 Edition

One engine, one number: faf-python-sdk scores all 33 slots exactly like faf-kernel — the same score faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2 give.

- **Always 33 slots.** The 12 enterprise slots count unless marked `slotignored`. 21 base slots filled with no markers: 64% (21/33). The same file plus the 12 markers: 100% (21/21). `faf auto` (faf-cli) writes the markers.
- `tbd` / `todo` are placeholders; short keys (`framework`, `css`, `state`, `api`, `db`, `pkg_manager`) are read.
- YAML is read the way the kernel reads it; unreadable YAML scores 0 without raising.
- `score_faf(yaml, tier=...)` still accepts `tier`; it no longer changes the slot count.
- **Upgrading:** `result.slots` lists all 33 slots under the kernel's names (`stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager`; were `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager`). Code that reads slots by name needs the new names. YAML the kernel can't read now scores 0 (a duplicate key, a second document, nesting deeper than 128), and rounding is half away from zero (12.5% → 13), as the kernel does.
- Parity harness: 845/845 fixtures match faf-kernel (`faf-scoring-kernel@3.0.0`), including the `project.faf` of 58 public repos.

See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.

## v1.4.0 — The Interop Edition

The interop functions get their real names: `author_agents_md` / `author_gemini_md` are public, `render_*` is the impl, `generate_*` is deprecated (removed in 2.0).

Output is byte-identical — a naming change, not a behaviour change. Existing `from faf_sdk import generate_agents_md` keeps working, now with a `DeprecationWarning`.

`faf_sdk.interop` — `author_agents_md(faf)` and `author_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.

```python
from faf_sdk import parse_file, author_agents_md

faf = parse_file("project.faf")
print(author_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
```

Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll one. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.

## v1.2.0 — The Dart Edition

Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.

```python
from faf_sdk import detect_dart_project

d = detect_dart_project(".")
print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
```

## v1.1.0

**Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.

- `score_faf()` — Mk4 scoring with 21-slot Base or 33-slot Enterprise tiers
- 100% parity with `faf-wasm-sdk` (Rust) and `faf-cli` (TypeScript)
- 3 crash bugs fixed (malformed YAML, null project fields)
- 175 tests including 88 WJTTC championship-grade tests (concurrency, adversarial input, security)

**Why this matters:** If you're building on FAF in Python — MCP servers, Gemini extensions, CI pipelines — your scores now match every other FAF tool exactly. No more "it scored 85% in the CLI but 60% in Python." One engine, one truth.

> **v1.1.2** is a patch release — package description aligned with the canonical "Persistent project context for Python" framing. CHANGELOG.md added. No code changes.

## Installation

```bash
pip install faf-python-sdk
```

## Quick Start

```python
from faf_sdk import parse_file, score_faf

# Parse a .faf file
faf = parse_file("project.faf")
print(f"Project: {faf.project_name}")

# Score it with the Mk4 engine
with open("project.faf") as f:
    result = score_faf(f.read())

print(f"Score: {result.score}% {result.tier}")
print(f"Slots: {result.populated}/{result.total} populated")
```

> **FAF defines. MD instructs. AI codes.**

## Mk4 Scoring

The Mk4 engine scores `.faf` files against 33 slots (project metadata, human context, tech stack, and 12 enterprise slots), exactly as faf-kernel does. Each slot is **Populated**, **Empty**, or **Slotignored**. The score is populated ÷ active, where active = 33 − slotignored.

```python
from faf_sdk import score_faf

result = score_faf(yaml_content)
print(result.score)      # 0-100
print(result.tier)       # TROPHY / GOLD / SILVER / BRONZE / GREEN / YELLOW / RED / WHITE
print(result.populated)  # slots with real data
print(result.active)     # 33 minus slotignored
print(result.slots)      # per-slot breakdown, 33 entries in kernel order
```

**Placeholder rejection:** Values like `"null"`, `"none"`, `"unknown"`, `"n/a"`, `"tbd"`, `"todo"`, `"Describe your project goal"` (case-insensitive) are scored as Empty — not Populated.

**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A project that does not use the 12 enterprise slots marks them `slotignored` (`faf auto` writes them) and can still reach 100%.

**Short keys:** `stack.framework`, `css`, `state`, `api`, `db`, `pkg_manager` are the canonical names; the legacy `frontend`, `css_framework`, `state_management`, `api_type`, `database`, `package_manager` are read when the short key is empty.

## Parsing

```python
from faf_sdk import parse, parse_file, stringify

# Parse from string or file
faf = parse(yaml_content)
faf = parse_file("project.faf")

# Typed access
print(faf.data.project.name)
print(faf.data.project.goal)
print(faf.data.stack.backend)
print(faf.data.human_context.who)

# Raw dict access
print(faf.raw["project"]["goal"])

# Convert back to YAML
yaml_str = stringify(faf)
```

## Validation

```python
from faf_sdk import validate

result = validate(faf)

if result.valid:
    print(f"Valid! Score: {result.score}%")
else:
    print("Errors:", result.errors)

print("Warnings:", result.warnings)
```

## File Discovery

```python
from faf_sdk import find_faf_file, find_project_root

# Find project.faf (walks up directory tree)
path = find_faf_file("/path/to/src")

# Find project root by markers (package.json, pyproject.toml, .git, etc.)
root = find_project_root()
```

## API Reference

| Function | Returns | Description |
|----------|---------|-------------|
| `score_faf(yaml)` | `Mk4Result` | Mk4 score, always 33 slots (faf-kernel parity) |
| `parse(content)` | `FafFile` | Parse YAML string |
| `parse_file(path)` | `FafFile` | Parse from file path |
| `validate(faf)` | `ValidationResult` | Structure validation + warnings |
| `stringify(data)` | `str` | Convert back to YAML |
| `find_faf_file(dir?)` | `str \| None` | Find project.faf in tree |
| `find_project_root(dir?)` | `str \| None` | Find project root |

## FAF Ecosystem

| Package | Platform | Registry |
|---------|----------|----------|
| **faf-python-sdk** | **Python foundation** | **PyPI** |
| [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google Gemini | PyPI |
| [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |
| [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
| [faf-cli](https://npmjs.com/package/faf-cli) | CLI | npm |

If `faf-python-sdk` has been useful, consider starring the repo — it helps others find it.

## Links

- **Site:** [faf.one](https://faf.one)
- **IANA Registration:** [application/vnd.faf+yaml](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
- **Gemini MCP:** [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/)

## License

MIT
