faf-python-sdk 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

{faf_python_sdk-1.3.0.dist-info → faf_python_sdk-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.3.0
+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,25 +41,27 @@ 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.0 — 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).
 
-`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.
+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, 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 a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+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.
 
 ## What's New in v1.2.0 — The Dart Edition
 

{faf_python_sdk-1.3.0.dist-info → faf_python_sdk-1.4.0.dist-info}/RECORD

@@ -1,14 +1,14 @@
-faf_sdk/__init__.py,sha256=1ARRF6IEkjcvf0zJwqWQF30TjTGtgrzWi8O3YwigASc,1842
+faf_sdk/__init__.py,sha256=D7XMrdOQ2LwwBVErSosZrnMCbGLppBrTT1f9BcR8dsY,2020
 faf_sdk/dart_detection.json,sha256=jFtKnyyMVVFsunizteFZ2pLhYC1qC2nCIWQB9SdOqKE,1195
 faf_sdk/detect.py,sha256=GothQNKChKSEwke74MRy63VyBYLqOzN1j3yzjsSVpJA,6310
 faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
-faf_sdk/interop.py,sha256=fgIm13pLZIxSrjJiq7ZXXvR5ViWezuGUxhzCbsz_eZQ,13465
+faf_sdk/interop.py,sha256=GWGjBEMAYhoDs7lUpZ6sqtE-I5qCcSwQ2QYLJcjXgvA,14776
 faf_sdk/mk4.py,sha256=dA8o3YB0W19Mt_bqcR67HAw4S08zxj6IzEmubTy-pQY,5708
 faf_sdk/parser.py,sha256=lJJysj52X0Q_aGhl4PMXY2PuMqASFHdVRiSZFDdampk,4925
 faf_sdk/types.py,sha256=sm1ezSzCc-93bszr4ite31_xZRKjwqf2utlqN6_0QuM,6615
 faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
 faf_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-faf_python_sdk-1.3.0.dist-info/METADATA,sha256=L_RFAhO35YJ9RRSGyl5M8IIdFBU6rndw5bnKmUJmBpk,8784
-faf_python_sdk-1.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-faf_python_sdk-1.3.0.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
-faf_python_sdk-1.3.0.dist-info/RECORD,,
+faf_python_sdk-1.4.0.dist-info/METADATA,sha256=n7nME8V10mhLGXYYvt7lVeEp21V_CMpOAzAbcBT3X6M,9021
+faf_python_sdk-1.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+faf_python_sdk-1.4.0.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
+faf_python_sdk-1.4.0.dist-info/RECORD,,

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.0"
+__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_sdk/interop.py

@@ -1,5 +1,5 @@
 """
-AI-context file generators — AGENTS.md and GEMINI.md from .faf data.
+AI-context file authoring — AGENTS.md and GEMINI.md from .faf data.
 
 Python port of faf-cli's `src/interop/agents.ts` + `gemini.ts`, kept in
 parity with the canonical TypeScript. Deterministic projection from curated
@@ -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 ----------------------------------------------------------
 
@@ -90,7 +100,7 @@ def slot_label(path: str) -> str:
 
 
 def faf_meta_tag(faf: dict) -> str:
-    """The two-line `<!-- faf: ... -->` metastamp every faf-generated file opens with."""
+    """The two-line `<!-- faf: ... -->` metastamp every faf-authored file opens with."""
     proj = faf.get("project") or {}
     name = str(proj.get("name") or "").strip()
     lang = str(proj.get("main_language") or "").strip()
@@ -102,7 +112,7 @@ def faf_meta_tag(faf: dict) -> str:
     return f"{line1}\n{line2}"
 
 
-# --- command classification (shared by both generators) ---------------------
+# --- command classification (shared by both) --------------------------------
 
 def _classify_commands(faf: dict) -> dict:
     commands = faf.get("commands") or {}
@@ -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:
@@ -187,9 +200,9 @@ def generate_agents_md(faf: dict) -> str:
         push(orientation)
         push()
     push(
-        "> Authored by faf — refresh with `faf export --agents` or the "
-        "`faf_agents` MCP tool. The managed block is regenerated each time; "
-        "hand-written content outside it is preserved."
+        "> Authored by faf — do not edit the managed block; refresh with "
+        "`faf export --agents` or the `faf_agents` MCP tool. Hand-written "
+        "content outside it is preserved."
     )
     push()
 
@@ -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)