faf-python-sdk 1.0.2__tar.gz → 1.1.0__tar.gz

faf_python_sdk-1.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: faf-python-sdk
+Version: 1.1.0
+Summary: Python SDK for FAF (Foundational AI-context Format) - 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
+
+> **Python SDK for FAF** — parse, validate, and score `.faf` files with the Mk4 Championship Scoring Engine. The foundation for [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/).
+
+[![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-175%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 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.
+
+## 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")
+```
+
+## Mk4 Scoring
+
+The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+
+```python
+from faf_sdk import score_faf, LicenseTier
+
+# Base scoring (21 slots)
+result = score_faf(yaml_content)
+print(result.score)      # 0-100
+print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.populated)  # slots with real data
+print(result.active)     # total minus slotignored
+print(result.slots)      # per-slot breakdown
+
+# Enterprise scoring (33 slots — adds monorepo/infra)
+result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+```
+
+**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+
+## 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, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `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 |
+
+## 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

faf_python_sdk-1.1.0/README.md

@@ -0,0 +1,148 @@
+# faf-python-sdk
+
+> **Python SDK for FAF** — parse, validate, and score `.faf` files with the Mk4 Championship Scoring Engine. The foundation for [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/).
+
+[![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-175%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 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.
+
+## 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")
+```
+
+## Mk4 Scoring
+
+The Mk4 engine scores `.faf` files by checking 21 universal slots (project metadata, human context, tech stack). Each slot is **Populated**, **Empty**, or **Slotignored**. The score is the percentage of active slots that are populated.
+
+```python
+from faf_sdk import score_faf, LicenseTier
+
+# Base scoring (21 slots)
+result = score_faf(yaml_content)
+print(result.score)      # 0-100
+print(result.tier)       # Trophy/Gold/Silver/Bronze/Green/Yellow/Red
+print(result.populated)  # slots with real data
+print(result.active)     # total minus slotignored
+print(result.slots)      # per-slot breakdown
+
+# Enterprise scoring (33 slots — adds monorepo/infra)
+result = score_faf(yaml_content, LicenseTier.ENTERPRISE)
+```
+
+**Placeholder rejection:** Values like `"null"`, `"unknown"`, `"n/a"`, `"Describe your project goal"` are detected and scored as Empty — not Populated.
+
+**Slotignored:** Set any slot to `slotignored` to exclude it from scoring. A backend-only project can mark `frontend: slotignored` and still reach 100%.
+
+## 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, tier?)` | `Mk4Result` | Mk4 score (21 or 33 slots) |
+| `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 |
+
+## 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

{faf_python_sdk-1.0.2 → faf_python_sdk-1.1.0}/docs/GROK-INTEGRATION.md

@@ -284,7 +284,7 @@ Common errors:
 The SDK includes comprehensive tests:
 
 ```bash
-pip install faf-sdk[dev]
+pip install faf-python-sdk[dev]
 pytest tests/ -v
 ```
 

{faf_python_sdk-1.0.2 → faf_python_sdk-1.1.0}/faf_sdk/__init__.py

@@ -19,6 +19,7 @@ Usage:
 
 from .parser import parse, parse_file, stringify, FafFile
 from .validator import validate, ValidationResult
+from .mk4 import score_faf, Mk4Result, SlotState, LicenseTier
 from .discovery import find_faf_file, find_project_root, load_fafignore
 from .types import (
     FafData,
@@ -30,7 +31,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __all__ = [
     # Parser
     "parse",
@@ -40,6 +41,11 @@ __all__ = [
     # Validator
     "validate",
     "ValidationResult",
+    # Mk4 Scoring Engine
+    "score_faf",
+    "Mk4Result",
+    "SlotState",
+    "LicenseTier",
     # Discovery
     "find_faf_file",
     "find_project_root",

faf_python_sdk-1.1.0/faf_sdk/mk4.py

@@ -0,0 +1,214 @@
+"""
+Mk4 Championship Engine — 33-Slot Scoring
+
+Ported from faf-wasm-sdk/src/mk4.rs (100% parity).
+Philosophy: Populated, Empty, or Slotignored.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Tuple, Dict, Any
+
+import yaml
+
+
+class SlotState(Enum):
+    EMPTY = "empty"
+    POPULATED = "populated"
+    SLOTIGNORED = "slotignored"
+
+
+class LicenseTier(Enum):
+    BASE = "base"
+    ENTERPRISE = "enterprise"
+
+
+@dataclass
+class Mk4Result:
+    score: int
+    tier: str
+    populated: int
+    ignored: int
+    active: int
+    total: int
+    slots: List[Tuple[str, SlotState]]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "score": self.score,
+            "tier": self.tier,
+            "populated": self.populated,
+            "empty": self.total - self.populated - self.ignored,
+            "ignored": self.ignored,
+            "active": self.active,
+            "total": self.total,
+            "slots": {name: state.value for name, state in self.slots},
+        }
+
+
+# 8 placeholder strings — case-insensitive rejection (mk4.rs lines 224-233)
+_PLACEHOLDERS = frozenset([
+    "describe your project goal",
+    "development teams",
+    "cloud platform",
+    "null",
+    "none",
+    "unknown",
+    "n/a",
+    "not applicable",
+])
+
+
+def score_faf(yaml_content: str, tier: LicenseTier = LicenseTier.BASE) -> Mk4Result:
+    """Calculate the official FAF Mk4 score from YAML content."""
+    try:
+        doc = yaml.safe_load(yaml_content)
+    except yaml.YAMLError:
+        doc = {}
+    if not isinstance(doc, dict):
+        doc = {}
+
+    slot_paths = _get_slot_paths(tier)
+    populated = 0
+    ignored = 0
+    slots: List[Tuple[str, SlotState]] = []
+
+    for path in slot_paths:
+        state = _get_slot_state(doc, path)
+        if state == SlotState.POPULATED:
+            populated += 1
+        elif state == SlotState.SLOTIGNORED:
+            ignored += 1
+        slots.append((path, state))
+
+    total = 33 if tier == LicenseTier.ENTERPRISE else 21
+    active = total - ignored
+
+    if active == 0:
+        score_val = 0
+    else:
+        score_val = round((populated / active) * 100)
+
+    return Mk4Result(
+        score=score_val,
+        tier=_score_to_tier(score_val),
+        populated=populated,
+        ignored=ignored,
+        active=active,
+        total=total,
+        slots=slots,
+    )
+
+
+def _get_slot_paths(tier: LicenseTier) -> List[str]:
+    """The Universal DNA Map — exact order from mk4.rs lines 126-176."""
+    slots = [
+        # Project Meta (3)
+        "project.name",
+        "project.goal",
+        "project.main_language",
+        # Human Context (6)
+        "human_context.who",
+        "human_context.what",
+        "human_context.why",
+        "human_context.where",
+        "human_context.when",
+        "human_context.how",
+        # Frontend Stack (4)
+        "stack.frontend",
+        "stack.css_framework",
+        "stack.ui_library",
+        "stack.state_management",
+        # Backend Stack (5)
+        "stack.backend",
+        "stack.api_type",
+        "stack.runtime",
+        "stack.database",
+        "stack.connection",
+        # Universal Stack (3)
+        "stack.hosting",
+        "stack.build",
+        "stack.cicd",
+    ]
+
+    if tier == LicenseTier.ENTERPRISE:
+        slots.extend([
+            # Enterprise Infra (5)
+            "stack.monorepo_tool",
+            "stack.package_manager",
+            "stack.workspaces",
+            "monorepo.packages_count",
+            "monorepo.build_orchestrator",
+            # Enterprise App (4)
+            "stack.admin",
+            "stack.cache",
+            "stack.search",
+            "stack.storage",
+            # Enterprise Ops (3)
+            "monorepo.versioning_strategy",
+            "monorepo.shared_configs",
+            "monorepo.remote_cache",
+        ])
+
+    return slots
+
+
+def _get_slot_state(doc: dict, path: str) -> SlotState:
+    """Determine the state of a specific slot (mk4.rs lines 179-219)."""
+    parts = path.split(".")
+    current = doc
+
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return SlotState.EMPTY
+
+    # None = YAML null/~ (mk4.rs line 217: _ => Empty)
+    if current is None:
+        return SlotState.EMPTY
+
+    # String values (mk4.rs lines 192-200)
+    if isinstance(current, str):
+        s = current.strip()
+        if s == "slotignored":
+            return SlotState.SLOTIGNORED
+        if _is_valid_populated(s):
+            return SlotState.POPULATED
+        return SlotState.EMPTY
+
+    # Numbers and bools — always Populated (mk4.rs line 202)
+    if isinstance(current, (int, float, bool)):
+        return SlotState.POPULATED
+
+    # Sequences — Populated if non-empty (mk4.rs lines 203-209)
+    if isinstance(current, list):
+        return SlotState.POPULATED if current else SlotState.EMPTY
+
+    # Mappings — Populated if non-empty (mk4.rs lines 210-216)
+    if isinstance(current, dict):
+        return SlotState.POPULATED if current else SlotState.EMPTY
+
+    return SlotState.EMPTY
+
+
+def _is_valid_populated(s: str) -> bool:
+    """Placeholder rejection — 8 magic strings (mk4.rs lines 223-236)."""
+    return len(s) > 0 and s.lower() not in _PLACEHOLDERS
+
+
+def _score_to_tier(score: int) -> str:
+    """Mk4 official tier calculation (mk4.rs lines 239-247)."""
+    if score >= 100:
+        return "\U0001f3c6"   # Trophy
+    if score >= 99:
+        return "\U0001f947"   # Gold
+    if score >= 95:
+        return "\U0001f948"   # Silver
+    if score >= 85:
+        return "\U0001f949"   # Bronze
+    if score >= 70:
+        return "\U0001f7e2"   # Green
+    if score >= 55:
+        return "\U0001f7e1"   # Yellow
+    return "\U0001f534"       # Red

{faf_python_sdk-1.0.2 → faf_python_sdk-1.1.0}/faf_sdk/parser.py

@@ -183,7 +183,7 @@ def get_field(faf: FafFile, *keys: str, default: Any = None) -> Any:
         >>> name = get_field(faf, "project", "name")
         >>> stack = get_field(faf, "stack", "frontend", default="None")
     """
-    value = faf.raw
+    value: Any = faf.raw
     for key in keys:
         if isinstance(value, dict):
             value = value.get(key)

{faf_python_sdk-1.0.2 → faf_python_sdk-1.1.0}/faf_sdk/types.py

@@ -129,6 +129,8 @@ class FafData:
         project_data = data.get("project", {})
         if isinstance(project_data, str):
             project_data = {"name": project_data}
+        elif not isinstance(project_data, dict):
+            project_data = {}
 
         project = ProjectInfo(
             name=project_data.get("name", "unknown"),

faf_python_sdk-1.1.0/project.faf

@@ -0,0 +1,25 @@
+faf_version: '2.5.0'
+project:
+  name: faf-python-sdk
+  goal: Python SDK for parsing, validating, and scoring .faf files with Mk4 Championship Engine
+  main_language: Python
+human_context:
+  who: Python developers building AI tools, MCP servers, and CI pipelines
+  what: Parse, validate, and score FAF project DNA files with 100% Mk4 parity
+  why: Universal scoring across all FAF tools — same slots, same formula, same scores
+  where: PyPI (pip install faf-python-sdk)
+  when: Every AI session that needs project context
+  how: Import faf_sdk, call score_faf() or parse_file()
+stack:
+  frontend: slotignored
+  css_framework: slotignored
+  ui_library: slotignored
+  state_management: slotignored
+  backend: Python
+  api_type: SDK (library)
+  runtime: Python 3.8+
+  database: slotignored
+  connection: slotignored
+  hosting: PyPI
+  build: hatchling
+  cicd: GitHub Actions

{faf_python_sdk-1.0.2 → faf_python_sdk-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faf-python-sdk"
-version = "1.0.2"
+version = "1.1.0"
 description = "Python SDK for FAF (Foundational AI-context Format) - IANA-registered application/vnd.faf+yaml"
 readme = "README.md"
 license = {text = "MIT"}
@@ -56,7 +56,7 @@ Issues = "https://github.com/Wolfe-Jam/faf-python-sdk/issues"
 packages = ["faf_sdk"]
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "3.9"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true