faf-python-sdk 1.0.0__py3-none-any.whl

faf_python_sdk-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+faf_sdk/__init__.py,sha256=HIxYtzcWZ3NcO0FoxB2PGStw1R0ZAybBrMVcsdxpRII,1105
+faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
+faf_sdk/parser.py,sha256=mlG5XG5T-JBhgE8udXleKxUt-rb2MOebGkGmCieuNKY,4920
+faf_sdk/types.py,sha256=B0r80EjGGo941u0b_RNyqOmqODEajf-pJ1sWtZ6ew74,6536
+faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
+faf_python_sdk-1.0.0.dist-info/METADATA,sha256=f4k9JchM1mbZHRzavoKtAa5FEpGq3NnRo_Or8uamDGw,5431
+faf_python_sdk-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+faf_python_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
+faf_python_sdk-1.0.0.dist-info/RECORD,,

faf_python_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

faf_python_sdk-1.0.0.dist-info/licenses/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_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""
+FAF Python SDK - Foundational AI-context Format
+
+IANA-registered: application/vnd.faf+yaml
+https://faf.one
+
+Usage:
+    from faf_sdk import parse, validate, find_faf_file, FafFile
+
+    # Parse a .faf file
+    faf = parse(content)
+
+    # Validate structure
+    errors, warnings = validate(faf)
+
+    # Find project.faf in directory tree
+    path = find_faf_file("/path/to/project")
+"""
+
+from .parser import parse, parse_file, stringify, FafFile
+from .validator import validate, ValidationResult
+from .discovery import find_faf_file, find_project_root, load_fafignore
+from .types import (
+    FafData,
+    ProjectInfo,
+    StackInfo,
+    InstantContext,
+    ContextQuality,
+    HumanContext,
+    AIScoring
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    # Parser
+    "parse",
+    "parse_file",
+    "stringify",
+    "FafFile",
+    # Validator
+    "validate",
+    "ValidationResult",
+    # Discovery
+    "find_faf_file",
+    "find_project_root",
+    "load_fafignore",
+    # Types
+    "FafData",
+    "ProjectInfo",
+    "StackInfo",
+    "InstantContext",
+    "ContextQuality",
+    "HumanContext",
+    "AIScoring",
+]

faf_sdk/discovery.py

@@ -0,0 +1,378 @@
+"""
+FAF file discovery - find .faf files and project roots
+
+Mirrors claude-faf-mcp/src/faf-core/utils/file-utils.ts and fafignore-parser.ts
+"""
+
+import os
+import fnmatch
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+
+# Default ignore patterns (from TypeScript implementation)
+DEFAULT_IGNORE_PATTERNS = [
+    # Dependencies
+    "node_modules/",
+    "vendor/",
+    "bower_components/",
+    "__pycache__/",
+    "*.pyc",
+    ".pytest_cache/",
+    "venv/",
+    ".venv/",
+    "env/",
+    ".env/",
+
+    # Build outputs
+    "dist/",
+    "build/",
+    "out/",
+    ".next/",
+    ".nuxt/",
+    ".svelte-kit/",
+    "target/",
+    "bin/",
+    "obj/",
+
+    # Version control
+    ".git/",
+    ".svn/",
+    ".hg/",
+
+    # IDE/Editor
+    ".vscode/",
+    ".idea/",
+    "*.swp",
+    "*.swo",
+    "*~",
+
+    # OS files
+    ".DS_Store",
+    "Thumbs.db",
+
+    # Logs
+    "*.log",
+    "logs/",
+    "npm-debug.log*",
+    "yarn-debug.log*",
+    "yarn-error.log*",
+
+    # Secrets/Config
+    ".env",
+    ".env.*",
+    "*.key",
+    "*.pem",
+    "*.p12",
+    "credentials.json",
+    "secrets/",
+
+    # Test coverage
+    "coverage/",
+    ".nyc_output/",
+    "htmlcov/",
+
+    # Large media (usually not needed for context)
+    "*.jpg",
+    "*.jpeg",
+    "*.png",
+    "*.gif",
+    "*.ico",
+    "*.svg",
+    "*.mp4",
+    "*.mp3",
+    "*.wav",
+    "*.pdf",
+    "*.zip",
+    "*.tar.gz",
+    "*.rar",
+
+    # Lock files (verbose)
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "Pipfile.lock",
+
+    # Misc
+    ".cache/",
+    "tmp/",
+    "temp/",
+]
+
+
+def find_faf_file(start_dir: Optional[str] = None,
+                   max_depth: int = 10) -> Optional[str]:
+    """
+    Find project.faf or .faf file by walking up directory tree
+
+    Args:
+        start_dir: Directory to start search (default: cwd)
+        max_depth: Maximum parent directories to check
+
+    Returns:
+        Absolute path to .faf file, or None if not found
+
+    Example:
+        >>> path = find_faf_file("/path/to/project/src")
+        >>> if path:
+        ...     print(f"Found: {path}")
+    """
+    if start_dir is None:
+        start_dir = os.getcwd()
+
+    current = Path(start_dir).resolve()
+
+    for _ in range(max_depth):
+        # Check for modern project.faf (preferred)
+        project_faf = current / "project.faf"
+        if project_faf.exists():
+            return str(project_faf)
+
+        # Check for legacy .faf
+        legacy_faf = current / ".faf"
+        if legacy_faf.exists():
+            return str(legacy_faf)
+
+        # Move up to parent
+        parent = current.parent
+        if parent == current:
+            # Reached filesystem root
+            break
+        current = parent
+
+    return None
+
+
+def find_project_root(start_dir: Optional[str] = None,
+                       max_depth: int = 10) -> Optional[str]:
+    """
+    Find project root by looking for common project markers
+
+    Looks for: package.json, pyproject.toml, Cargo.toml, go.mod, etc.
+
+    Args:
+        start_dir: Directory to start search (default: cwd)
+        max_depth: Maximum parent directories to check
+
+    Returns:
+        Absolute path to project root, or None if not found
+
+    Example:
+        >>> root = find_project_root()
+        >>> print(f"Project root: {root}")
+    """
+    if start_dir is None:
+        start_dir = os.getcwd()
+
+    markers = [
+        "package.json",
+        "pyproject.toml",
+        "setup.py",
+        "requirements.txt",
+        "Cargo.toml",
+        "go.mod",
+        "pom.xml",
+        "build.gradle",
+        "Gemfile",
+        ".git",
+        "project.faf",
+        ".faf",
+    ]
+
+    current = Path(start_dir).resolve()
+
+    for _ in range(max_depth):
+        for marker in markers:
+            if (current / marker).exists():
+                return str(current)
+
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+
+    return None
+
+
+def load_fafignore(project_root: str) -> List[str]:
+    """
+    Load .fafignore patterns from project root
+
+    Falls back to default patterns if no .fafignore exists.
+
+    Args:
+        project_root: Path to project root directory
+
+    Returns:
+        List of ignore patterns
+
+    Example:
+        >>> patterns = load_fafignore("/path/to/project")
+        >>> for p in patterns[:5]:
+        ...     print(p)
+    """
+    fafignore_path = Path(project_root) / ".fafignore"
+
+    if not fafignore_path.exists():
+        return DEFAULT_IGNORE_PATTERNS.copy()
+
+    patterns = []
+    try:
+        with open(fafignore_path, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                # Skip empty lines and comments
+                if line and not line.startswith('#'):
+                    patterns.append(line)
+    except IOError:
+        return DEFAULT_IGNORE_PATTERNS.copy()
+
+    return patterns if patterns else DEFAULT_IGNORE_PATTERNS.copy()
+
+
+def should_ignore(file_path: str, patterns: List[str]) -> bool:
+    """
+    Check if a file path should be ignored based on patterns
+
+    Args:
+        file_path: Relative file path to check
+        patterns: List of ignore patterns
+
+    Returns:
+        True if file should be ignored
+
+    Example:
+        >>> patterns = load_fafignore(root)
+        >>> if not should_ignore("src/main.py", patterns):
+        ...     process_file("src/main.py")
+    """
+    # Normalize path separators
+    file_path = file_path.replace('\\', '/')
+
+    for pattern in patterns:
+        # Handle directory patterns (ending with /)
+        if pattern.endswith('/'):
+            dir_pattern = pattern.rstrip('/')
+            if file_path.startswith(dir_pattern + '/') or file_path == dir_pattern:
+                return True
+            # Check if any component matches
+            parts = file_path.split('/')
+            if dir_pattern in parts:
+                return True
+        else:
+            # File pattern
+            if fnmatch.fnmatch(file_path, pattern):
+                return True
+            # Also check basename
+            if fnmatch.fnmatch(os.path.basename(file_path), pattern):
+                return True
+
+    return False
+
+
+def list_project_files(project_root: str,
+                        ignore_patterns: Optional[List[str]] = None,
+                        extensions: Optional[List[str]] = None) -> List[str]:
+    """
+    List all project files, respecting .fafignore
+
+    Args:
+        project_root: Path to project root
+        ignore_patterns: Custom ignore patterns (default: load from .fafignore)
+        extensions: Filter by extensions (e.g., [".py", ".ts"])
+
+    Returns:
+        List of relative file paths
+
+    Example:
+        >>> files = list_project_files(root, extensions=[".py", ".ts"])
+        >>> print(f"Found {len(files)} source files")
+    """
+    if ignore_patterns is None:
+        ignore_patterns = load_fafignore(project_root)
+
+    root = Path(project_root)
+    files = []
+
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+
+        relative = str(path.relative_to(root))
+
+        # Check ignore patterns
+        if should_ignore(relative, ignore_patterns):
+            continue
+
+        # Check extensions filter
+        if extensions:
+            if path.suffix.lower() not in extensions:
+                continue
+
+        files.append(relative)
+
+    return sorted(files)
+
+
+def create_default_fafignore(project_root: str) -> str:
+    """
+    Create a default .fafignore file
+
+    Args:
+        project_root: Path to project root
+
+    Returns:
+        Path to created .fafignore file
+
+    Example:
+        >>> path = create_default_fafignore(root)
+        >>> print(f"Created: {path}")
+    """
+    fafignore_path = Path(project_root) / ".fafignore"
+
+    content = [
+        "# .fafignore - Files to exclude from FAF context",
+        "# Similar to .gitignore syntax",
+        "",
+        "# Dependencies",
+        "node_modules/",
+        "__pycache__/",
+        "venv/",
+        ".venv/",
+        "",
+        "# Build outputs",
+        "dist/",
+        "build/",
+        ".next/",
+        "",
+        "# Version control",
+        ".git/",
+        "",
+        "# IDE",
+        ".vscode/",
+        ".idea/",
+        "",
+        "# Secrets",
+        ".env",
+        ".env.*",
+        "*.key",
+        "*.pem",
+        "",
+        "# Large files",
+        "*.jpg",
+        "*.png",
+        "*.mp4",
+        "*.pdf",
+        "*.zip",
+        "",
+        "# Lock files",
+        "package-lock.json",
+        "yarn.lock",
+        "",
+    ]
+
+    with open(fafignore_path, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(content))
+
+    return str(fafignore_path)

faf_sdk/parser.py

@@ -0,0 +1,194 @@
+"""
+Core FAF parser - YAML parsing with validation
+
+Mirrors the TypeScript fix-once/yaml.ts implementation for cross-language compatibility.
+"""
+
+import yaml
+from typing import Any, Dict, Optional, Union
+from dataclasses import dataclass
+
+from .types import FafData
+
+
+class FafParseError(Exception):
+    """Raised when FAF parsing fails"""
+    pass
+
+
+@dataclass
+class FafFile:
+    """
+    Parsed FAF file with both raw and typed access
+
+    Attributes:
+        data: Typed FafData object with all sections
+        raw: Raw dictionary from YAML parsing
+        path: Optional file path if loaded from disk
+    """
+    data: FafData
+    raw: Dict[str, Any]
+    path: Optional[str] = None
+
+    @property
+    def project_name(self) -> str:
+        """Quick access to project name"""
+        return self.data.project.name
+
+    @property
+    def score(self) -> Optional[int]:
+        """Quick access to AI score"""
+        return self.data.ai_score
+
+    @property
+    def version(self) -> str:
+        """Quick access to FAF version"""
+        return self.data.faf_version
+
+
+def parse(content: Union[str, None], path: Optional[str] = None) -> FafFile:
+    """
+    Parse FAF content from string
+
+    Args:
+        content: YAML string content of .faf file
+        path: Optional file path for error messages
+
+    Returns:
+        FafFile object with parsed data
+
+    Raises:
+        FafParseError: If content is invalid
+
+    Example:
+        >>> content = open("project.faf").read()
+        >>> faf = parse(content)
+        >>> print(faf.project_name)
+        'my-project'
+    """
+    # Handle null/empty content
+    if content is None:
+        raise FafParseError("Content is null or undefined")
+
+    if not isinstance(content, str):
+        raise FafParseError(f"Content must be string, got {type(content).__name__}")
+
+    content = content.strip()
+    if not content:
+        raise FafParseError("Content is empty")
+
+    # Parse YAML
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        location = f" in {path}" if path else ""
+        raise FafParseError(f"Invalid YAML syntax{location}: {e}")
+
+    # Validate structure
+    if data is None:
+        raise FafParseError("YAML parsed to null - file may be empty or all comments")
+
+    if not isinstance(data, dict):
+        raise FafParseError(
+            f"FAF must be a YAML object/dictionary, got {type(data).__name__}. "
+            "Arrays and primitives are not valid FAF files."
+        )
+
+    # Convert to typed structure
+    try:
+        faf_data = FafData.from_dict(data)
+    except Exception as e:
+        raise FafParseError(f"Failed to parse FAF structure: {e}")
+
+    return FafFile(
+        data=faf_data,
+        raw=data,
+        path=path
+    )
+
+
+def parse_file(filepath: str) -> FafFile:
+    """
+    Parse FAF from file path
+
+    Args:
+        filepath: Path to .faf file
+
+    Returns:
+        FafFile object with parsed data
+
+    Raises:
+        FafParseError: If file cannot be read or parsed
+        FileNotFoundError: If file doesn't exist
+
+    Example:
+        >>> faf = parse_file("project.faf")
+        >>> print(faf.data.instant_context.tech_stack)
+    """
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"FAF file not found: {filepath}")
+    except IOError as e:
+        raise FafParseError(f"Failed to read {filepath}: {e}")
+
+    return parse(content, path=filepath)
+
+
+def stringify(data: Union[Dict[str, Any], FafFile, FafData],
+              default_flow_style: bool = False) -> str:
+    """
+    Convert FAF data back to YAML string
+
+    Args:
+        data: Dictionary, FafFile, or FafData to serialize
+        default_flow_style: Use flow style for collections
+
+    Returns:
+        YAML string
+
+    Example:
+        >>> yaml_str = stringify(faf.raw)
+        >>> with open("output.faf", "w") as f:
+        ...     f.write(yaml_str)
+    """
+    if isinstance(data, FafFile):
+        data = data.raw
+    elif isinstance(data, FafData):
+        data = data.raw
+
+    return yaml.dump(
+        data,
+        default_flow_style=default_flow_style,
+        allow_unicode=True,
+        sort_keys=False,
+        indent=2
+    )
+
+
+def get_field(faf: FafFile, *keys: str, default: Any = None) -> Any:
+    """
+    Safely get nested field from FAF raw data
+
+    Args:
+        faf: Parsed FafFile
+        *keys: Path to field (e.g., "project", "name")
+        default: Default value if not found
+
+    Returns:
+        Field value or default
+
+    Example:
+        >>> name = get_field(faf, "project", "name")
+        >>> stack = get_field(faf, "stack", "frontend", default="None")
+    """
+    value = faf.raw
+    for key in keys:
+        if isinstance(value, dict):
+            value = value.get(key)
+        else:
+            return default
+        if value is None:
+            return default
+    return value

faf_sdk/types.py

@@ -0,0 +1,211 @@
+"""
+Type definitions for FAF (Foundational AI-context Format)
+
+These mirror the TypeScript definitions in faf-cli for cross-language compatibility.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ProjectInfo:
+    """Core project metadata"""
+    name: str
+    goal: Optional[str] = None
+    main_language: Optional[str] = None
+    approach: Optional[str] = None
+    version: Optional[str] = None
+    license: Optional[str] = None
+
+
+@dataclass
+class StackInfo:
+    """Technical stack breakdown"""
+    frontend: Optional[str] = None
+    backend: Optional[str] = None
+    database: Optional[str] = None
+    infrastructure: Optional[str] = None
+    build_tool: Optional[str] = None
+    testing: Optional[str] = None
+    cicd: Optional[str] = None
+
+
+@dataclass
+class InstantContext:
+    """Quick context for AI understanding"""
+    what_building: Optional[str] = None
+    tech_stack: Optional[str] = None
+    deployment: Optional[str] = None
+    key_files: List[str] = field(default_factory=list)
+    commands: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ContextQuality:
+    """Quality metrics for the FAF file"""
+    slots_filled: Optional[str] = None
+    confidence: Optional[str] = None
+    handoff_ready: bool = False
+    missing_context: List[str] = field(default_factory=list)
+
+
+@dataclass
+class HumanContext:
+    """The 6 W's - human-readable context"""
+    who: Optional[str] = None  # Target users
+    what: Optional[str] = None  # Core problem
+    why: Optional[str] = None   # Mission/purpose
+    how: Optional[str] = None   # Approach
+    where: Optional[str] = None # Deployment
+    when: Optional[str] = None  # Timeline
+
+
+@dataclass
+class AIScoring:
+    """AI-readiness scoring system"""
+    score: Optional[int] = None  # 0-100
+    confidence: Optional[str] = None  # LOW, MEDIUM, HIGH
+    version: Optional[str] = None
+
+
+@dataclass
+class AIInstructions:
+    """Instructions for AI assistants"""
+    working_style: Optional[str] = None
+    quality_bar: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)
+    focus_areas: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Preferences:
+    """Development preferences"""
+    quality_bar: Optional[str] = None
+    testing: Optional[str] = None
+    documentation: Optional[str] = None
+    code_style: Optional[str] = None
+
+
+@dataclass
+class State:
+    """Project state tracking"""
+    phase: Optional[str] = None
+    version: Optional[str] = None
+    focus: Optional[str] = None
+    milestones: List[str] = field(default_factory=list)
+
+
+@dataclass
+class FafData:
+    """
+    Complete FAF file structure
+
+    Represents the full parsed content of a .faf file.
+    All fields are optional except faf_version and project.
+    """
+    faf_version: str
+    project: ProjectInfo
+
+    # Optional sections
+    ai_score: Optional[int] = None
+    ai_confidence: Optional[str] = None
+    ai_tldr: Optional[Dict[str, str]] = None
+    instant_context: Optional[InstantContext] = None
+    context_quality: Optional[ContextQuality] = None
+    stack: Optional[StackInfo] = None
+    human_context: Optional[HumanContext] = None
+    ai_instructions: Optional[AIInstructions] = None
+    preferences: Optional[Preferences] = None
+    state: Optional[State] = None
+    tags: List[str] = field(default_factory=list)
+
+    # Raw data for unrecognized fields
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FafData":
+        """Create FafData from parsed YAML dictionary"""
+        project_data = data.get("project", {})
+        if isinstance(project_data, str):
+            project_data = {"name": project_data}
+
+        project = ProjectInfo(
+            name=project_data.get("name", "unknown"),
+            goal=project_data.get("goal"),
+            main_language=project_data.get("main_language"),
+            approach=project_data.get("approach"),
+            version=project_data.get("version"),
+            license=project_data.get("license")
+        )
+
+        # Parse instant_context
+        instant_ctx = None
+        if "instant_context" in data:
+            ic = data["instant_context"]
+            instant_ctx = InstantContext(
+                what_building=ic.get("what_building"),
+                tech_stack=ic.get("tech_stack"),
+                deployment=ic.get("deployment"),
+                key_files=ic.get("key_files", []),
+                commands=ic.get("commands", {})
+            )
+
+        # Parse stack
+        stack = None
+        if "stack" in data:
+            s = data["stack"]
+            stack = StackInfo(
+                frontend=s.get("frontend"),
+                backend=s.get("backend"),
+                database=s.get("database"),
+                infrastructure=s.get("infrastructure"),
+                build_tool=s.get("build_tool"),
+                testing=s.get("testing"),
+                cicd=s.get("cicd")
+            )
+
+        # Parse context_quality
+        ctx_quality = None
+        if "context_quality" in data:
+            cq = data["context_quality"]
+            ctx_quality = ContextQuality(
+                slots_filled=cq.get("slots_filled"),
+                confidence=cq.get("confidence"),
+                handoff_ready=cq.get("handoff_ready", False),
+                missing_context=cq.get("missing_context", [])
+            )
+
+        # Parse human_context
+        human_ctx = None
+        if "human_context" in data:
+            hc = data["human_context"]
+            human_ctx = HumanContext(
+                who=hc.get("who"),
+                what=hc.get("what"),
+                why=hc.get("why"),
+                how=hc.get("how"),
+                where=hc.get("where"),
+                when=hc.get("when")
+            )
+
+        # Parse AI score
+        ai_score = data.get("ai_score")
+        if isinstance(ai_score, str) and ai_score.endswith("%"):
+            ai_score = int(ai_score.rstrip("%"))
+
+        return cls(
+            faf_version=data.get("faf_version", "2.5.0"),
+            project=project,
+            ai_score=ai_score,
+            ai_confidence=data.get("ai_confidence"),
+            ai_tldr=data.get("ai_tldr"),
+            instant_context=instant_ctx,
+            context_quality=ctx_quality,
+            stack=stack,
+            human_context=human_ctx,
+            preferences=None,  # Add parsing if needed
+            state=None,  # Add parsing if needed
+            tags=data.get("tags", []),
+            raw=data
+        )

faf_sdk/validator.py

@@ -0,0 +1,213 @@
+"""
+FAF validation - check structure and completeness
+
+Mirrors claude-faf-mcp/src/faf-core/commands/validate.ts
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple, Union
+
+from .parser import FafFile, parse
+
+
+@dataclass
+class ValidationResult:
+    """
+    Result of FAF validation
+
+    Attributes:
+        valid: True if no errors (warnings OK)
+        errors: List of critical errors
+        warnings: List of non-critical warnings
+        score: Calculated completeness score (0-100)
+    """
+    valid: bool
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    score: int = 0
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+
+def validate(faf: Union[FafFile, Dict[str, Any], str]) -> ValidationResult:
+    """
+    Validate FAF file structure and completeness
+
+    Args:
+        faf: FafFile, raw dict, or YAML string to validate
+
+    Returns:
+        ValidationResult with errors, warnings, and score
+
+    Example:
+        >>> result = validate(faf)
+        >>> if not result.valid:
+        ...     print("Errors:", result.errors)
+        >>> print(f"Score: {result.score}%")
+    """
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    # Parse if string
+    if isinstance(faf, str):
+        try:
+            faf = parse(faf)
+        except Exception as e:
+            return ValidationResult(
+                valid=False,
+                errors=[f"Parse error: {e}"],
+                score=0
+            )
+
+    # Get raw data
+    if isinstance(faf, FafFile):
+        data = faf.raw
+    else:
+        data = faf
+
+    # Required fields
+    if "faf_version" not in data:
+        errors.append("Missing required field: faf_version")
+
+    if "project" not in data:
+        errors.append("Missing required field: project")
+    else:
+        project = data["project"]
+        if isinstance(project, dict):
+            if "name" not in project:
+                errors.append("Missing required field: project.name")
+        elif not isinstance(project, str):
+            errors.append("project must be object or string")
+
+    # Recommended sections
+    if "instant_context" not in data:
+        warnings.append("Missing recommended section: instant_context")
+    else:
+        ic = data["instant_context"]
+        if isinstance(ic, dict):
+            if "what_building" not in ic:
+                warnings.append("Missing instant_context.what_building")
+            if "tech_stack" not in ic:
+                warnings.append("Missing instant_context.tech_stack")
+
+    if "stack" not in data:
+        warnings.append("Missing recommended section: stack")
+
+    # Optional but useful
+    if "human_context" not in data:
+        warnings.append("Missing section: human_context (the 6 W's)")
+
+    if "ai_instructions" not in data:
+        warnings.append("Missing section: ai_instructions")
+
+    # Type validations
+    if "tags" in data and not isinstance(data["tags"], list):
+        errors.append("tags must be an array")
+
+    if "ai_score" in data:
+        score_val = data["ai_score"]
+        if isinstance(score_val, str):
+            if not score_val.endswith("%"):
+                warnings.append("ai_score should end with % (e.g., '85%')")
+        elif not isinstance(score_val, (int, float)):
+            errors.append("ai_score must be number or percentage string")
+
+    # Calculate completeness score
+    score = _calculate_score(data)
+
+    return ValidationResult(
+        valid=len(errors) == 0,
+        errors=errors,
+        warnings=warnings,
+        score=score
+    )
+
+
+def _calculate_score(data: Dict[str, Any]) -> int:
+    """
+    Calculate completeness score based on filled sections
+
+    Scoring breakdown:
+    - Required fields (30 points)
+    - Core sections (40 points)
+    - Extended sections (30 points)
+    """
+    score = 0
+    max_score = 100
+
+    # Required fields (30 points)
+    if "faf_version" in data:
+        score += 10
+    if "project" in data:
+        score += 10
+        project = data["project"]
+        if isinstance(project, dict):
+            if project.get("name"):
+                score += 5
+            if project.get("goal"):
+                score += 5
+
+    # Core sections (40 points)
+    if "instant_context" in data:
+        ic = data["instant_context"]
+        score += 5
+        if isinstance(ic, dict):
+            if ic.get("what_building"):
+                score += 5
+            if ic.get("tech_stack"):
+                score += 5
+            if ic.get("key_files"):
+                score += 5
+
+    if "stack" in data:
+        score += 10
+        stack = data["stack"]
+        if isinstance(stack, dict) and len(stack) > 2:
+            score += 5
+
+    if "context_quality" in data:
+        score += 5
+
+    # Extended sections (30 points)
+    if "human_context" in data:
+        score += 10
+
+    if "ai_instructions" in data:
+        score += 5
+
+    if "preferences" in data:
+        score += 5
+
+    if "state" in data:
+        score += 5
+
+    if data.get("tags"):
+        score += 5
+
+    return min(score, max_score)
+
+
+def validate_quick(content: str) -> Tuple[bool, str]:
+    """
+    Quick validation returning simple pass/fail with message
+
+    Args:
+        content: YAML string to validate
+
+    Returns:
+        Tuple of (valid, message)
+
+    Example:
+        >>> valid, msg = validate_quick(yaml_content)
+        >>> if not valid:
+        ...     print(f"Invalid: {msg}")
+    """
+    result = validate(content)
+
+    if not result.valid:
+        return False, f"Invalid: {'; '.join(result.errors)}"
+    elif result.warnings:
+        return True, f"Valid with warnings: {'; '.join(result.warnings[:2])}"
+    else:
+        return True, f"Valid (score: {result.score}%)"