faf-python-sdk 1.3.1__tar.gz → 1.4.0__tar.gz

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to faf-python-sdk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [1.4.0] - 2026-09-08 — 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).
+
+1.3.1 kept `generate_*` as "internal identifiers" — but a name that surfaces
+reflexively when reasoning about the tool lands in `tools/list` descriptions,
+host UIs, and docs. "Internal-only" holds only until someone documents it, so
+the public name has to be right now.
+
+### Added
+- `author_agents_md(faf)` / `author_gemini_md(faf)` — the public API names, in
+  the "faf authors" voice used on every documented surface. This is what
+  `faf_sdk.interop.__all__` advertises.
+- `render_agents_md(faf)` / `render_gemini_md(faf)` — the impl names: pure
+  `dict -> str` projection, pairs with the `write_*` helpers, greps clean. Same
+  split the canonical faf-cli TS uses.
+
+### Deprecated
+- `generate_agents_md` / `generate_gemini_md` — still work, now emit
+  `DeprecationWarning`, removed in 2.0. Point at `author_*`.
+
+### Notes
+- Additive + back-compatible: existing `from faf_sdk import generate_agents_md`
+  keeps working. No output change — the authored Markdown is byte-identical.
+
 ## [1.3.1] - 2026-09-07 — The Interop Edition
 
 Docs / copy patch — no API change.

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.3.1
+Version: 1.4.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
@@ -41,24 +41,24 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![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-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-216%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.3.1 — The Interop Edition
+## What's New in v1.4.0 — The Interop Edition
 
-The SDK can now author AI-context files, not just parse and score them.
+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).
 
-> **v1.3.1** is a copy patch — "generate" removed from external text (module docstring, the blockquote written into every AGENTS.md, README, CHANGELOG). No API change; the `faf_sdk.interop` functions below are unchanged.
+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` — `generate_agents_md(faf)` and `generate_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.
+`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, generate_agents_md
+from faf_sdk import parse_file, author_agents_md
 
 faf = parse_file("project.faf")
-print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+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.

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/README.md

@@ -9,24 +9,24 @@ The foundation other Python FAF tools build on. If you're building MCP servers,
 [![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-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-216%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.3.1 — The Interop Edition
+## What's New in v1.4.0 — The Interop Edition
 
-The SDK can now author AI-context files, not just parse and score them.
+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).
 
-> **v1.3.1** is a copy patch — "generate" removed from external text (module docstring, the blockquote written into every AGENTS.md, README, CHANGELOG). No API change; the `faf_sdk.interop` functions below are unchanged.
+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` — `generate_agents_md(faf)` and `generate_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.
+`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, generate_agents_md
+from faf_sdk import parse_file, author_agents_md
 
 faf = parse_file("project.faf")
-print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+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.

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/faf_sdk/__init__.py

@@ -25,7 +25,15 @@ 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 .detect import detect_dart_project, DartProject
-from .interop import generate_agents_md, generate_gemini_md, faf_meta_tag
+from .interop import (
+    author_agents_md,
+    author_gemini_md,
+    render_agents_md,
+    render_gemini_md,
+    generate_agents_md,  # deprecated alias — removed in 2.0
+    generate_gemini_md,  # deprecated alias — removed in 2.0
+    faf_meta_tag,
+)
 from .types import (
     FafData,
     ProjectInfo,
@@ -36,7 +44,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 __all__ = [
     # Parser
     "parse",
@@ -58,9 +66,9 @@ __all__ = [
     # Detection (Dart/Flutter — A+B hybrid, parity with faf-cli)
     "detect_dart_project",
     "DartProject",
-    # Interop — AGENTS.md / GEMINI.md generators (parity with faf-cli src/interop)
-    "generate_agents_md",
-    "generate_gemini_md",
+    # Interop — AGENTS.md / GEMINI.md authoring (parity with faf-cli src/interop)
+    "author_agents_md",
+    "author_gemini_md",
     "faf_meta_tag",
     # Types
     "FafData",

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/faf_sdk/interop.py

@@ -10,13 +10,23 @@ not agent ops.
 Both take the raw parsed .faf dict (`FafFile.data.raw`) — the .faf format
 carries top-level `commands` / `key_files` / `security` that the typed model
 doesn't surface.
+
+Naming: the impl functions are ``render_agents_md`` / ``render_gemini_md``
+(pure ``dict -> str`` projection, pairs with the writers). The public API
+name is ``author_agents_md`` / ``author_gemini_md`` — the surface consumers
+import, in the "faf authors" voice used on every documented surface.
+``generate_*`` is a deprecated alias, removed in 2.0.
 """
 
 from __future__ import annotations
 
+import warnings
 from typing import Any
 
-__all__ = ["generate_agents_md", "generate_gemini_md", "faf_meta_tag", "title_label", "slot_label"]
+__all__ = [
+    "author_agents_md", "author_gemini_md",
+    "faf_meta_tag", "title_label", "slot_label",
+]
 
 # --- shared helpers ----------------------------------------------------------
 
@@ -146,8 +156,11 @@ def _key_files(faf: dict) -> list:
 
 # --- AGENTS.md -------------------------------------------------------------
 
-def generate_agents_md(faf: dict) -> str:
-    """Author a BETTER-shaped AGENTS.md from raw .faf data. Deterministic."""
+def render_agents_md(faf: dict) -> str:
+    """Author a BETTER-shaped AGENTS.md from raw .faf data. Deterministic.
+
+    Public alias: :func:`author_agents_md`.
+    """
     lines: list[str] = []
 
     def push(s: str = "") -> None:
@@ -344,8 +357,11 @@ def generate_agents_md(faf: dict) -> str:
 
 # --- GEMINI.md ------------------------------------------------------------
 
-def generate_gemini_md(faf: dict) -> str:
-    """GEMINI.md — Gemini CLI's own convention (hierarchical, @file-importable)."""
+def render_gemini_md(faf: dict) -> str:
+    """GEMINI.md — Gemini CLI's own convention (hierarchical, @file-importable).
+
+    Public alias: :func:`author_gemini_md`.
+    """
     lines: list[str] = []
     proj = faf.get("project") or {}
     cmds = _classify_commands(faf)
@@ -401,3 +417,31 @@ def generate_gemini_md(faf: dict) -> str:
         "",
     ]
     return "\n".join(lines)
+
+
+# --- public + deprecated names --------------------------------------------
+
+#: Public API name for :func:`render_agents_md` — "faf authors" voice.
+author_agents_md = render_agents_md
+#: Public API name for :func:`render_gemini_md`.
+author_gemini_md = render_gemini_md
+
+
+def generate_agents_md(faf: dict) -> str:
+    """Deprecated alias for :func:`author_agents_md`. Removed in 2.0."""
+    warnings.warn(
+        "generate_agents_md is deprecated; use author_agents_md",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return render_agents_md(faf)
+
+
+def generate_gemini_md(faf: dict) -> str:
+    """Deprecated alias for :func:`author_gemini_md`. Removed in 2.0."""
+    warnings.warn(
+        "generate_gemini_md is deprecated; use author_gemini_md",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return render_gemini_md(faf)

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faf-python-sdk"
-version = "1.3.1"
+version = "1.4.0"
 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"}

{faf_python_sdk-1.3.1 → faf_python_sdk-1.4.0}/tests/test_interop.py

@@ -1,6 +1,8 @@
-"""Tests for faf_sdk.interop — AGENTS.md / GEMINI.md generators."""
+"""Tests for faf_sdk.interop — AGENTS.md / GEMINI.md authoring."""
 
-from faf_sdk import faf_meta_tag, generate_agents_md, generate_gemini_md
+import pytest
+
+from faf_sdk import faf_meta_tag, render_agents_md, render_gemini_md
 from faf_sdk.interop import slot_label, title_label
 
 # A representative .faf as the raw parsed dict.
@@ -64,7 +66,7 @@ def test_faf_meta_tag_two_lines():
 # --- AGENTS.md -----------------------------------------------------------
 
 def test_agents_md_sections_present():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     for section in (
         "# AGENTS.md — widget-api",
         "## Setup & build",
@@ -82,14 +84,14 @@ def test_agents_md_sections_present():
 
 
 def test_agents_md_omits_human_context():
-    md = generate_agents_md({**SAMPLE, "human_context": {"who": "devs", "why": "money"}})
+    md = render_agents_md({**SAMPLE, "human_context": {"who": "devs", "why": "money"}})
     assert "## Human Context" not in md
     assert "## Context" not in md
     assert "money" not in md
 
 
 def test_agents_md_setup_ordered_install_build_dev():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     block = md.split("## Setup & build")[1].split("```")[1]
     # first line is the ```bash language tag
     lines = [ln for ln in block.strip().splitlines()][1:]
@@ -99,7 +101,7 @@ def test_agents_md_setup_ordered_install_build_dev():
 
 
 def test_agents_md_guardrails_always_render_even_with_no_data():
-    md = generate_agents_md({"faf_version": "3.0", "project": {"name": "bare"}})
+    md = render_agents_md({"faf_version": "3.0", "project": {"name": "bare"}})
     assert "## Guardrails" in md
     assert "## Definition of Done" in md
     assert "## Commit & PR" in md
@@ -107,28 +109,28 @@ def test_agents_md_guardrails_always_render_even_with_no_data():
 
 
 def test_agents_md_key_files_table_when_roles_present():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     assert "| Path | Role |" in md
     assert "| `src/server.ts` | the entry point |" in md
 
 
 def test_agents_md_security_never_leaks_values():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     assert "Secrets live in `.env`" in md
     assert "see `.env.example`" in md
 
 
 def test_agents_md_stack_drops_non_stack_marketing_keys():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     assert "developers" not in md.split("## Stack")[1]  # target_user filtered
 
 
 def test_agents_md_deterministic():
-    assert generate_agents_md(SAMPLE) == generate_agents_md(dict(SAMPLE))
+    assert render_agents_md(SAMPLE) == render_agents_md(dict(SAMPLE))
 
 
 def test_agents_md_human_prefs_excluded_from_conventions():
-    md = generate_agents_md(SAMPLE)
+    md = render_agents_md(SAMPLE)
     conv = md.split("## Conventions")[1].split("##")[0]
     assert "communication" not in conv.lower()
     assert "Testing" in conv
@@ -137,7 +139,7 @@ def test_agents_md_human_prefs_excluded_from_conventions():
 # --- GEMINI.md ----------------------------------------------------------
 
 def test_gemini_md_structure():
-    md = generate_gemini_md(SAMPLE)
+    md = render_gemini_md(SAMPLE)
     assert md.startswith("<!-- faf:")
     assert "# GEMINI.md — widget-api" in md
     assert "Project: widget-api" in md
@@ -148,7 +150,7 @@ def test_gemini_md_structure():
 
 def test_gemini_md_no_guardrail_ladder():
     # GEMINI.md is lighter — no Definition of Done / When stuck
-    md = generate_gemini_md(SAMPLE)
+    md = render_gemini_md(SAMPLE)
     assert "## Definition of Done" not in md
     assert "## Guardrails" not in md
 
@@ -157,8 +159,8 @@ def test_gemini_md_no_guardrail_ladder():
 
 def test_minimal_faf_does_not_crash():
     minimal = {"faf_version": "3.0", "project": {"name": "x"}}
-    assert "# AGENTS.md — x" in generate_agents_md(minimal)
-    assert "# GEMINI.md — x" in generate_gemini_md(minimal)
+    assert "# AGENTS.md — x" in render_agents_md(minimal)
+    assert "# GEMINI.md — x" in render_gemini_md(minimal)
 
 
 def test_key_files_from_instant_context_fallback():
@@ -167,12 +169,41 @@ def test_key_files_from_instant_context_fallback():
         "project": {"name": "y"},
         "instant_context": {"key_files": ["a.py", "b.py"]},
     }
-    md = generate_agents_md(faf)
+    md = render_agents_md(faf)
     assert "- `a.py`" in md
 
 
 def test_commands_from_instant_context_are_not_used_at_toplevel():
     # top-level `commands` is the source; instant_context.commands is separate
     faf = {"faf_version": "3.0", "project": {"name": "z"}, "commands": {"test": "go test ./..."}}
-    md = generate_agents_md(faf)
+    md = render_agents_md(faf)
     assert "go test ./..." in md
+
+
+# --- naming: public alias + deprecated shim ------------------------------
+
+def test_author_names_are_the_public_alias():
+    from faf_sdk import author_agents_md, author_gemini_md
+
+    assert author_agents_md is render_agents_md
+    assert author_gemini_md is render_gemini_md
+
+
+def test_generate_names_still_work_but_warn():
+    from faf_sdk import generate_agents_md, generate_gemini_md
+
+    with pytest.warns(DeprecationWarning, match="author_agents_md"):
+        md = generate_agents_md(SAMPLE)
+    assert md == render_agents_md(SAMPLE)
+
+    with pytest.warns(DeprecationWarning, match="author_gemini_md"):
+        assert generate_gemini_md(SAMPLE) == render_gemini_md(SAMPLE)
+
+
+def test_interop_all_advertises_author_not_generate():
+    from faf_sdk import interop
+
+    assert "author_agents_md" in interop.__all__
+    assert "author_gemini_md" in interop.__all__
+    assert "generate_agents_md" not in interop.__all__
+    assert "render_agents_md" not in interop.__all__  # importable, not advertised