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

faf_python_sdk-1.1.2/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to faf-python-sdk are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [1.1.2] - 2026-04-26
+
+### Changed
+- Package description aligned with the canonical "Persistent project context for Python" framing on PyPI catalog and GitHub repo metadata.
+- README lede sharpened — leads with the value proposition and the audience (MCP server / CI validator / tool authors), no longer feature-list framing.
+
+### Added
+- `CHANGELOG.md` (this file) — versioned release history, separate from the README's "What's New" section.
+- Brand mantra `FAF defines. MD instructs. AI codes.` anchored in the README and `__init__.py` module docstring.
+
+### Notes
+No runtime code changes. Patch release to surface description alignment in the PyPI catalog and tighten positioning copy. The catalog only updates on a new publish.
+
+## [1.1.1] - 2026-04-18
+
+### Fixed
+- Tier alignment to match faf-cli v6 — clean geometric symbols, no emoji. v1.1.0 mistakenly returned emoji tiers; this patch normalizes them to plain uppercase strings (`TROPHY`, `GOLD`, `SILVER`, `BRONZE`, `GREEN`, `YELLOW`, `RED`).
+
+## [1.1.0] - 2026-03-29
+
+### Added
+- **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.
+- `score_faf()` — Mk4 scoring with 21-slot Base or 33-slot Enterprise tiers.
+- 100% parity with `faf-wasm-sdk` (Rust) and `faf-cli` (TypeScript).
+- 88 new WJTTC championship-grade tests (concurrency, adversarial input, security).
+- Total test count: 175 (was 87).
+
+### Fixed
+- 3 crash bugs in malformed YAML and null project field handling.
+
+## [1.0.2] - earlier
+
+### Added
+- Initial public release with `parse`, `parse_file`, `stringify`, `validate`, `find_faf_file`, `find_project_root`, and the typed `FafData` model.

faf_python_sdk-1.1.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant, v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its code of conduct. The full text of that covenant governs behavior in this project and its community spaces.
+
+## Summary
+
+- We commit to maintaining a respectful, harassment-free environment for everyone who participates, regardless of background.
+- Participation includes contributing code, opening issues, reviewing pull requests, and interacting in any official channel.
+- The Contributor Covenant defines the full scope, expected conduct, and enforcement guidelines. See the link above for the complete text.
+
+## Reporting
+
+If you observe conduct that violates this Code of Conduct, please email **team@faf.one**. Reports are handled confidentially. Maintainers will review, respond, and take appropriate action consistent with the Contributor Covenant's enforcement guidelines.
+
+## Scope
+
+This Code of Conduct applies to all project spaces — the repository, issues, pull requests, discussions, and any public communication channels operated by the project. It also applies when representing the project in other forums.
+
+## Attribution
+
+This Code of Conduct adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), available under the CC BY 4.0 license.

{faf_python_sdk-1.1.0 → faf_python_sdk-1.1.2}/PKG-INFO

@@ -1,7 +1,7 @@
 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
+Version: 1.1.2
+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
@@ -32,7 +32,9 @@ 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/).
+**Persistent project context for Python.** Parse, validate, and score `.faf` files — 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.
 
 [![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/)
@@ -52,6 +54,8 @@ Description-Content-Type: text/markdown
 
 **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
@@ -75,6 +79,8 @@ 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 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.

{faf_python_sdk-1.1.0 → faf_python_sdk-1.1.2}/README.md

@@ -1,6 +1,8 @@
 # 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/).
+**Persistent project context for Python.** Parse, validate, and score `.faf` files — 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.
 
 [![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/)
@@ -20,6 +22,8 @@
 
 **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
@@ -43,6 +47,8 @@ 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 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.

faf_python_sdk-1.1.2/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+We provide security updates for the latest released version. For older versions, please upgrade to the current release.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please email **security@faf.one** directly.
+
+**Please do not open a public GitHub issue for security reports.** Responsible disclosure gives us time to fix the issue before it's widely known.
+
+When reporting, please include:
+- A description of the vulnerability
+- Steps to reproduce
+- Affected versions (if known)
+- Any suggested fix (optional)
+
+We aim to respond within 7 days.

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

@@ -1,20 +1,23 @@
 """
-FAF Python SDK - Foundational AI-context Format
+faf-python-sdk — Persistent project context for Python.
 
-IANA-registered: application/vnd.faf+yaml
-https://faf.one
+Parse, validate, and score `.faf` files. The foundation other Python
+FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on.
+
+IANA-registered media type: application/vnd.faf+yaml
+Site: https://faf.one
 
 Usage:
-    from faf_sdk import parse, validate, find_faf_file, FafFile
+    from faf_sdk import parse_file, score_faf
 
-    # Parse a .faf file
-    faf = parse(content)
+    faf = parse_file("project.faf")
+    print(faf.data.project.name)
 
-    # Validate structure
-    errors, warnings = validate(faf)
+    with open("project.faf") as f:
+        result = score_faf(f.read())
+    print(f"Score: {result.score}% {result.tier}")
 
-    # Find project.faf in directory tree
-    path = find_faf_file("/path/to/project")
+FAF defines. MD instructs. AI codes.
 """
 
 from .parser import parse, parse_file, stringify, FafFile
@@ -31,7 +34,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.1.0"
+__version__ = "1.1.2"
 __all__ = [
     # Parser
     "parse",

{faf_python_sdk-1.1.0 → faf_python_sdk-1.1.2}/faf_sdk/mk4.py

@@ -198,17 +198,19 @@ def _is_valid_populated(s: str) -> bool:
 
 
 def _score_to_tier(score: int) -> str:
-    """Mk4 official tier calculation (mk4.rs lines 239-247)."""
+    """Mk4 official tier calculation — aligned with faf-cli v6 tiers.ts."""
     if score >= 100:
-        return "\U0001f3c6"   # Trophy
+        return "TROPHY"
     if score >= 99:
-        return "\U0001f947"   # Gold
+        return "GOLD"
     if score >= 95:
-        return "\U0001f948"   # Silver
+        return "SILVER"
     if score >= 85:
-        return "\U0001f949"   # Bronze
+        return "BRONZE"
     if score >= 70:
-        return "\U0001f7e2"   # Green
+        return "GREEN"
     if score >= 55:
-        return "\U0001f7e1"   # Yellow
-    return "\U0001f534"       # Red
+        return "YELLOW"
+    if score >= 1:
+        return "RED"
+    return "WHITE"

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

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faf-python-sdk"
-version = "1.1.0"
-description = "Python SDK for FAF (Foundational AI-context Format) - IANA-registered application/vnd.faf+yaml"
+version = "1.1.2"
+description = "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."
 readme = "README.md"
 license = {text = "MIT"}
 authors = [

{faf_python_sdk-1.1.0 → faf_python_sdk-1.1.2}/tests/test_mk4.py

@@ -89,7 +89,7 @@ stack:
         assert result.populated == 21
         assert result.total == 21
         assert result.score == 100
-        assert result.tier == "\U0001f3c6"  # Trophy
+        assert result.tier == "TROPHY"
 
     def test_enterprise_33_slots_total(self):
         result = score_faf("empty: true", LicenseTier.ENTERPRISE)
@@ -134,7 +134,7 @@ human_context:
         assert result.active == 17  # 21 - 4 = 17
         assert result.populated == 17
         assert result.score == 100  # 17/17 = 100%
-        assert result.tier == "\U0001f3c6"  # Trophy
+        assert result.tier == "TROPHY"
 
     def test_all_slotignored_scores_zero(self):
         yaml_content = """
@@ -350,44 +350,44 @@ project:
 
 class TestTiers:
     def test_tier_trophy_100(self):
-        assert _score_to_tier(100) == "\U0001f3c6"
+        assert _score_to_tier(100) == "TROPHY"
 
     def test_tier_gold_99(self):
-        assert _score_to_tier(99) == "\U0001f947"
+        assert _score_to_tier(99) == "GOLD"
 
     def test_tier_silver_95(self):
-        assert _score_to_tier(95) == "\U0001f948"
+        assert _score_to_tier(95) == "SILVER"
 
     def test_tier_bronze_85(self):
-        assert _score_to_tier(85) == "\U0001f949"
+        assert _score_to_tier(85) == "BRONZE"
 
     def test_tier_green_70(self):
-        assert _score_to_tier(70) == "\U0001f7e2"
+        assert _score_to_tier(70) == "GREEN"
 
     def test_tier_yellow_55(self):
-        assert _score_to_tier(55) == "\U0001f7e1"
+        assert _score_to_tier(55) == "YELLOW"
 
     def test_tier_red_54(self):
-        assert _score_to_tier(54) == "\U0001f534"
+        assert _score_to_tier(54) == "RED"
 
     def test_tier_red_0(self):
-        assert _score_to_tier(0) == "\U0001f534"
+        assert _score_to_tier(0) == "WHITE"
 
     # Off-by-one boundaries
     def test_tier_boundary_98_is_silver(self):
-        assert _score_to_tier(98) == "\U0001f948"
+        assert _score_to_tier(98) == "SILVER"
 
     def test_tier_boundary_94_is_bronze(self):
-        assert _score_to_tier(94) == "\U0001f949"
+        assert _score_to_tier(94) == "BRONZE"
 
     def test_tier_boundary_84_is_green(self):
-        assert _score_to_tier(84) == "\U0001f7e2"
+        assert _score_to_tier(84) == "GREEN"
 
     def test_tier_boundary_69_is_yellow(self):
-        assert _score_to_tier(69) == "\U0001f7e1"
+        assert _score_to_tier(69) == "YELLOW"
 
     def test_tier_boundary_54_is_red(self):
-        assert _score_to_tier(54) == "\U0001f534"
+        assert _score_to_tier(54) == "RED"
 
 
 # =========================================================================
@@ -530,7 +530,7 @@ stack:
         result = score_faf(yaml_content)
         assert result.populated == 11
         assert result.score == 52  # 11/21 = 52.38 -> 52
-        assert result.tier == "\U0001f534"  # Red
+        assert result.tier == "RED"
 
     def test_mixed_enterprise_base_plus_some_enterprise(self):
         yaml_content = """
@@ -567,7 +567,7 @@ monorepo:
         assert result.populated == 24  # 21 base + 3 monorepo
         assert result.total == 33
         assert result.score == 73  # 24/33 = 72.7 -> 73
-        assert result.tier == "\U0001f7e2"  # Green
+        assert result.tier == "GREEN"
 
     def test_enterprise_full_33_slots_populated(self):
         yaml_content = """
@@ -613,4 +613,4 @@ monorepo:
         assert result.populated == 33
         assert result.total == 33
         assert result.score == 100
-        assert result.tier == "\U0001f3c6"  # Trophy
+        assert result.tier == "TROPHY"