faf-python-sdk 1.0.0__tar.gz

faf_python_sdk-1.0.0/.github/workflows/pypi.yml

@@ -0,0 +1,14 @@
+name: Publish to PyPI
+on: workflow_dispatch
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

faf_python_sdk-1.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

faf_python_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wolfejam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

faf_python_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: faf-python-sdk
+Version: 1.0.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-sdk
+
+Python SDK for **FAF (Foundational AI-context Format)** - the IANA-registered format for AI project context.
+
+**Media Type:** `application/vnd.faf+yaml`
+
+## Installation
+
+```bash
+pip install faf-sdk
+```
+
+## Quick Start
+
+```python
+from faf_sdk import parse, validate, find_faf_file
+
+# Find and parse project.faf
+path = find_faf_file()
+if path:
+    with open(path) as f:
+        faf = parse(f.read())
+
+    print(f"Project: {faf.project_name}")
+    print(f"Score: {faf.score}%")
+    print(f"Stack: {faf.data.instant_context.tech_stack}")
+```
+
+## Core Functions
+
+### Parsing
+
+```python
+from faf_sdk import parse, parse_file, stringify
+
+# Parse from string
+faf = parse(yaml_content)
+
+# Parse from file
+faf = parse_file("project.faf")
+
+# Access typed data
+print(faf.data.project.name)
+print(faf.data.instant_context.what_building)
+print(faf.data.stack.frontend)
+
+# Access raw dict
+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, load_fafignore
+
+# Find project.faf (walks up directory tree)
+path = find_faf_file("/path/to/src")
+
+# Find project root
+root = find_project_root()
+
+# Load ignore patterns
+patterns = load_fafignore(root)
+```
+
+## FAF File Structure
+
+A `.faf` file provides instant project context for AI:
+
+```yaml
+faf_version: 2.5.0
+ai_score: 85%
+ai_confidence: HIGH
+
+project:
+  name: my-project
+  goal: Build a CLI tool for data processing
+
+instant_context:
+  what_building: CLI data processing tool
+  tech_stack: Python 3.11, Click, Pandas
+  key_files:
+    - src/cli.py
+    - src/processor.py
+
+stack:
+  frontend: None
+  backend: Python
+  database: SQLite
+  infrastructure: Docker
+
+human_context:
+  who: Data analysts
+  what: Process CSV files efficiently
+  why: Current tools are slow
+```
+
+## Type Definitions
+
+The SDK provides typed access to all FAF sections:
+
+```python
+from faf_sdk import (
+    FafData,
+    ProjectInfo,
+    StackInfo,
+    InstantContext,
+    ContextQuality,
+    HumanContext
+)
+
+# All fields are optional except faf_version and project.name
+faf = parse(content)
+
+# Typed access
+project: ProjectInfo = faf.data.project
+stack: StackInfo = faf.data.stack
+context: InstantContext = faf.data.instant_context
+```
+
+## Integration Example
+
+```python
+from faf_sdk import find_faf_file, parse_file, validate
+
+def get_project_context():
+    """Load project context for AI processing"""
+    path = find_faf_file()
+    if not path:
+        return None
+
+    faf = parse_file(path)
+    result = validate(faf)
+
+    if not result.valid:
+        raise ValueError(f"Invalid FAF: {result.errors}")
+
+    return {
+        "name": faf.data.project.name,
+        "goal": faf.data.project.goal,
+        "stack": faf.data.instant_context.tech_stack if faf.data.instant_context else None,
+        "key_files": faf.data.instant_context.key_files if faf.data.instant_context else [],
+        "score": faf.score,
+    }
+
+# Use in AI context
+context = get_project_context()
+if context:
+    print(f"Working on: {context['name']}")
+    print(f"Goal: {context['goal']}")
+    print(f"Tech: {context['stack']}")
+```
+
+## Why FAF?
+
+Every AI conversation starts from zero. No memory of your project. No understanding of your stack. Just vibes.
+
+FAF solves this with a single, IANA-registered file that gives AI instant project context:
+
+- **One file, one read, full understanding**
+- **19ms average execution**
+- **Zero setup friction**
+- **MIT licensed, works everywhere**
+
+## Links
+
+- **Spec:** [github.com/Wolfe-Jam/faf](https://github.com/Wolfe-Jam/faf)
+- **Site:** [faf.one](https://faf.one)
+- **MCP Server:** [claude-faf-mcp](https://github.com/modelcontextprotocol/servers/tree/main/src/faf)
+- **IANA Registration:** `application/vnd.faf+yaml`
+
+## License
+
+MIT

faf_python_sdk-1.0.0/README.md

@@ -0,0 +1,192 @@
+# faf-sdk
+
+Python SDK for **FAF (Foundational AI-context Format)** - the IANA-registered format for AI project context.
+
+**Media Type:** `application/vnd.faf+yaml`
+
+## Installation
+
+```bash
+pip install faf-sdk
+```
+
+## Quick Start
+
+```python
+from faf_sdk import parse, validate, find_faf_file
+
+# Find and parse project.faf
+path = find_faf_file()
+if path:
+    with open(path) as f:
+        faf = parse(f.read())
+
+    print(f"Project: {faf.project_name}")
+    print(f"Score: {faf.score}%")
+    print(f"Stack: {faf.data.instant_context.tech_stack}")
+```
+
+## Core Functions
+
+### Parsing
+
+```python
+from faf_sdk import parse, parse_file, stringify
+
+# Parse from string
+faf = parse(yaml_content)
+
+# Parse from file
+faf = parse_file("project.faf")
+
+# Access typed data
+print(faf.data.project.name)
+print(faf.data.instant_context.what_building)
+print(faf.data.stack.frontend)
+
+# Access raw dict
+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, load_fafignore
+
+# Find project.faf (walks up directory tree)
+path = find_faf_file("/path/to/src")
+
+# Find project root
+root = find_project_root()
+
+# Load ignore patterns
+patterns = load_fafignore(root)
+```
+
+## FAF File Structure
+
+A `.faf` file provides instant project context for AI:
+
+```yaml
+faf_version: 2.5.0
+ai_score: 85%
+ai_confidence: HIGH
+
+project:
+  name: my-project
+  goal: Build a CLI tool for data processing
+
+instant_context:
+  what_building: CLI data processing tool
+  tech_stack: Python 3.11, Click, Pandas
+  key_files:
+    - src/cli.py
+    - src/processor.py
+
+stack:
+  frontend: None
+  backend: Python
+  database: SQLite
+  infrastructure: Docker
+
+human_context:
+  who: Data analysts
+  what: Process CSV files efficiently
+  why: Current tools are slow
+```
+
+## Type Definitions
+
+The SDK provides typed access to all FAF sections:
+
+```python
+from faf_sdk import (
+    FafData,
+    ProjectInfo,
+    StackInfo,
+    InstantContext,
+    ContextQuality,
+    HumanContext
+)
+
+# All fields are optional except faf_version and project.name
+faf = parse(content)
+
+# Typed access
+project: ProjectInfo = faf.data.project
+stack: StackInfo = faf.data.stack
+context: InstantContext = faf.data.instant_context
+```
+
+## Integration Example
+
+```python
+from faf_sdk import find_faf_file, parse_file, validate
+
+def get_project_context():
+    """Load project context for AI processing"""
+    path = find_faf_file()
+    if not path:
+        return None
+
+    faf = parse_file(path)
+    result = validate(faf)
+
+    if not result.valid:
+        raise ValueError(f"Invalid FAF: {result.errors}")
+
+    return {
+        "name": faf.data.project.name,
+        "goal": faf.data.project.goal,
+        "stack": faf.data.instant_context.tech_stack if faf.data.instant_context else None,
+        "key_files": faf.data.instant_context.key_files if faf.data.instant_context else [],
+        "score": faf.score,
+    }
+
+# Use in AI context
+context = get_project_context()
+if context:
+    print(f"Working on: {context['name']}")
+    print(f"Goal: {context['goal']}")
+    print(f"Tech: {context['stack']}")
+```
+
+## Why FAF?
+
+Every AI conversation starts from zero. No memory of your project. No understanding of your stack. Just vibes.
+
+FAF solves this with a single, IANA-registered file that gives AI instant project context:
+
+- **One file, one read, full understanding**
+- **19ms average execution**
+- **Zero setup friction**
+- **MIT licensed, works everywhere**
+
+## Links
+
+- **Spec:** [github.com/Wolfe-Jam/faf](https://github.com/Wolfe-Jam/faf)
+- **Site:** [faf.one](https://faf.one)
+- **MCP Server:** [claude-faf-mcp](https://github.com/modelcontextprotocol/servers/tree/main/src/faf)
+- **IANA Registration:** `application/vnd.faf+yaml`
+
+## License
+
+MIT