framesdkpy 0.3.0__tar.gz

framesdkpy-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+FrameSDK/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.env
+.env
+temp.txt

framesdkpy-0.3.0/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,218 @@
+# FrameSDK Implementation Summary
+
+**Date:** 2026-06-10
+**Version:** v0.3.0
+**Tests:** 82 passing (29 models + 25 translators + 22 validators + 6 loaders)
+
+## What was built
+
+FrameSDK is the Python SDK for FRAME. It provides a uniform interface for reading,
+validating, and working with FRAME project context files. Every downstream tool
+(Haxaml, CLIs, future frame-js) gets the same shaped answer from FrameSDK.
+
+### Architecture
+
+```
+frame/
+├── __init__.py                     # Top-level re-exports
+├── models/                         # Typed data carriers
+│   ├── base.py                     # FrameBaseModel -- to_dict, to_json, __repr__
+│   ├── facts_model.py              # FrameFacts, Profile, Architecture, Source, Quirk, OpenQuestion
+│   ├── rules_model.py              # FrameRules, Policy, CoreRule, Command, Dont, AskFirst, Hint
+│   ├── map_model.py                # FrameMap, Group, PathEntry, Entrypoint, ManagedPath, UnmappedPath
+│   ├── expect_model.py             # FrameExpect, MustHold, Check, Proof
+│   ├── acts_model.py               # FrameActs, Run, RunCheck, Blocker
+│   └── frame_model.py              # FRAME -- collates all five parts
+│
+├── loaders/                        # File discovery, parsing, assembly
+│   ├── yaml_reader.py              # Strict 5-file discovery + raw YAML parsing
+│   ├── assembler.py                # Dict → typed FRAME model construction
+│   └── __init__.py                 # load_frame() -- full pipeline orchestrator
+│
+├── validators/                     # Schema, limit, and cross-file validation
+│   ├── result.py                   # ValidationResult, ValidationError, ValidationWarning
+│   ├── schema_validator.py         # JSON Schema validation with local $ref resolution
+│   ├── limits_validator.py         # Character limit enforcement
+│   ├── cross_file_validator.py     # Cross-file schema_version and file/role checks
+│   └── __init__.py                 # validate_frame(), validate_file()
+│
+├── translators/                    # YAML ↔ JSON conversion
+│   ├── normalizer.py               # YAML quirk resolution (yes→True, ~→None, etc.)
+│   ├── yaml_to_json.py             # YAML file → clean JSON-compatible dict
+│   └── __init__.py                 # translate_file(), translate_directory()
+│
+├── computations/                   # Future: graph, cross-referencing
+└── helpers/                        # Future: shared utilities
+```
+
+### Pipeline (load_frame)
+
+```
+Directory path
+  ↓ yaml_reader.discover_frame_dir()
+  │   Verifies exactly 5 files: facts.yaml, rules.yaml, map.yaml, expect.yaml, acts.yaml
+  ↓ yaml_reader.read_raw_yaml()
+  │   Parses YAML into raw Python dicts (safe_load)
+  ↓ normalizer.normalize_dict()
+  │   Resolves YAML quirks: yes→True, no→False, ~→None, on/off→error
+  ↓ validators.validate_against_schema()
+  │   JSON Schema validation: types, required fields, enums
+  ↓ validators.validate_limits()
+  │   Character limits: enforced on core fields, advisory on descriptive
+  ↓ assembler.assemble_frame()
+  │   Cross-file check → builds typed FRAME object → returns
+```
+
+---
+
+## What each test suite verifies
+
+### test_models.py (29 tests)
+
+**FrameFacts (6 tests):**
+- Minimal construction with only required fields (profile, architecture)
+- Full construction with all optional sub-models populated
+- Required fields are non-nullable (Profile.name is str, not str|None)
+- Architecture.summary is required
+- to_dict() preserves nulls -- optional fields with None appear as keys with null values
+- to_json() produces valid parseable JSON
+
+**FrameRules (5 tests):**
+- Minimal construction with defaults (governance_level="normal")
+- Full construction with policies, commands, donts, ask_first, hints
+- Dont defaults to severity="critical"
+- Command has exactly three required fields (run, kind, purpose)
+- Commands dict serializes correctly
+
+**FrameMap (4 tests):**
+- Minimal construction with all empty lists
+- Full construction with groups, paths, entrypoints, managed_paths, unmapped_paths
+- PathEntry.id is optional (only needed for cross-referencing)
+- ManagedPath.id is optional (only needed for cross-referencing)
+
+**FrameExpect (3 tests):**
+- Minimal construction with empty checks and proof
+- Full construction with outcomes, must_hold, checks, proof
+- Various pass_condition formats work (exit_code, stdout contains)
+
+**FrameActs (4 tests):**
+- Minimal construction with empty runs and blockers
+- Full construction with run records and nested RunCheck objects
+- RunCheck with status=ran may have result=None (loader populates this)
+- RunCheck with status=skipped may have reason=None (loader populates this)
+
+**FRAME collation (4 tests):**
+- Minimal construction with only Facts (rules/map/expect/acts are None)
+- Full construction with all five parts populated
+- to_json() produces valid JSON with correct structure
+- repr() displays meaningful class name
+
+**Null preservation (3 tests):**
+- Optional fields with None appear as keys in to_dict()
+- Optional fields with None appear as keys in JSON output
+- Empty lists are preserved (not converted to null)
+
+### test_translators.py (25 tests)
+
+**Normalizer (13 tests):**
+- yes/Yes/YES/true/y → True
+- no/No/NO/false/n → False
+- ~ → None
+- null/Null/NULL → None
+- on/off raises TranslationError (ambiguous)
+- Empty string "" preserved as empty string (NOT coerced to None)
+- Python None stays None
+- Bare numbers pass through unchanged
+- Boolean values (already parsed by YAML) pass through
+- Regular strings pass through unchanged
+- Quoted "yes" in YAML (parsed as string by YAML lib) → normalized to True
+- Nested dicts normalize recursively
+- Nested lists normalize recursively
+
+**translate_to_dict (4 tests):**
+- Basic YAML string to dict
+- YAML with quirks (yes, no, ~, null)
+- Empty YAML returns empty dict
+- YAML with nested lists
+
+**translate_file (3 tests):**
+- Temp YAML file → translated dict
+- Nonexistent file raises FileNotFoundError
+- Wrong extension (.txt) raises ValueError
+
+**translate_directory (3 tests):**
+- Full directory with all 5 files → dict of dicts
+- Missing file raises FileNotFoundError
+- Nonexistent directory raises FileNotFoundError
+
+**translate_to_json_string (2 tests):**
+- Produces valid parseable JSON
+- JSON preserves types (True, 42, null)
+
+### test_validators.py (22 tests)
+
+**ValidationResult (6 tests):**
+- Empty result is valid and clean
+- Result with only warnings is valid but not clean
+- Result with errors is invalid
+- Merge combines errors and warnings from multiple results
+- add_error() convenience method populates expected/actual
+- summary() produces human-readable string
+
+**Schema validator (4 tests):**
+- Valid Facts dict passes schema validation
+- Missing required field (profile) is caught
+- Minimal valid Rules passes
+- All 5 file types pass with minimal valid data
+
+**Limits validator (4 tests):**
+- Value within limit passes
+- Core field (id) exceeding maxLength → error
+- Advisory field within limit → passes clean
+- Advisory field exceeding maxLength → warns, doesn't error
+
+**Cross-file validator (4 tests):**
+- All matching schema_versions pass
+- Version mismatch catches mismatched versions
+- Wrong file field catches file type mismatch
+- Wrong role field catches role mismatch
+
+**validate_frame (4 tests):**
+- Full valid directory passes end-to-end
+- Missing file raises FileNotFoundError
+- Schema version mismatch is caught
+- File/role mismatch is caught
+
+### test_loaders.py (6 tests)
+
+- load_frame() returns typed FRAME object with all parts present
+- Loaded FRAME serializes to JSON correctly
+- Missing file raises FileNotFoundError
+- Schema version mismatch raises FrameLoadError
+- Missing required Facts fields raises FrameLoadError
+- Nonexistent directory raises FileNotFoundError
+
+---
+
+## Audit findings
+
+### Stale files removed
+- `framesdkpy/loaders/loader.py` -- old generic loader, replaced by yaml_reader + assembler
+- `framesdkpy/models/model.py` -- old flat model, replaced by five typed model files
+- `framesdkpy/computations/report.py` -- old ValidationReport, replaced by ValidationResult
+- `framesdkpy/helpers/provisional.py` -- dead code, never referenced
+- `framesdkpy/validators/mechanical_validator.py` -- belongs in Haxaml, not FrameSDK
+
+### Over-engineering avoided
+- No separate assembler package -- lives inside loaders (Decision D6.5)
+- No Pydantic dependency -- pure dataclasses (Decision D4)
+- No graph/cross-reference computation yet -- deferring to future
+- No JSON-to-YAML translator yet -- low priority (Decision D15)
+- No abstract base class for validators -- simple functions returning result objects
+
+### Design consistency
+- Every module follows the same pattern: public API in __init__.py, implementation in sub-modules
+- All validators return result objects (never raise for validation failures)
+- All translators return clean dicts (never typed models)
+- All models inherit from FrameBaseModel for uniform serialization
+- Character limits enforced by field category (core vs advisory), not by blanket rules

framesdkpy-0.3.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: framesdkpy
+Version: 0.3.0
+Summary: Python SDK for FRAME -- typed project-context architecture for AI-assisted development
+Project-URL: Homepage, https://github.com/haxsysgit/FrameSDK
+Project-URL: Repository, https://github.com/haxsysgit/FrameSDK
+Author: Arinze Elenasulu
+License-Expression: MIT
+Keywords: agent-governance,ai-agents,frame,project-context
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: referencing>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FrameSDK
+
+The Python SDK for [FRAME](https://github.com/haxsysgit/FRAME) -- a typed project-context architecture for AI-assisted development.
+
+When you switch coding agents, the project forgets itself. Not its code -- the code is fine. But the *understanding*. The rules you agreed on. The decisions you made and why. The checks that matter. Things previous agents touched or broke.
+
+FRAME gives the project a typed shape that agents and tools read consistently. framesdkpy is how Python tools read that shape.
+
+## What it does
+
+Takes a `.haxaml/` directory with 5 YAML files and returns a typed `FRAME` object:
+
+```python
+from framesdkpy import load_frame
+
+frame = load_frame(".haxaml/")
+frame.facts.profile.name          # "Pharmax"
+frame.rules.governance_level      # "strict"
+frame.map.entrypoints[0].path     # "Backend/main.py"
+frame.expect.checks["backend_tests"].pass_condition  # "exit_code == 0"
+```
+
+Every downstream tool -- Haxaml, a CLI, a CI pipeline -- gets the same shaped answer. Cross-language SDKs return the same JSON shape.
+
+## Install
+
+```bash
+uv add framesdkpy
+# or
+pip install framesdkpy
+```
+
+Requires Python 3.11+. Three dependencies: PyYAML, jsonschema, referencing. That's it. No Pydantic, no heavy framework.
+
+## What's in the box
+
+- **loaders** -- `load_frame()` builds a typed FRAME from 5 YAML files. Strict single-directory discovery. Schema and character limit validation at load time.
+- **models** -- 27 typed dataclasses across 7 files. One import: `from framesdkpy.models import FRAME`.
+- **validators** -- Schema, character limits, cross-file consistency. Callable independently or through the loader.
+- **translators** -- YAML to JSON with full normalization. Handles yes/True, ~/None, on/off rejection.
+
+## Usage patterns
+
+```python
+from framesdkpy import load_frame, translate_directory, validate_file
+
+# Full pipeline -- load all 5 files, validate, assemble
+frame = load_frame(".haxaml/")
+
+# Translate YAML to clean dict (normalized, but no validation)
+data = translate_directory(".haxaml/")
+
+# Validate a single file without loading the full model
+result = validate_file(".haxaml/facts.yaml")
+print(result.summary())  # "valid" or "2 error(s), 1 warning(s)"
+
+# Serialize for cross-language use
+json_string = frame.to_json()
+```
+
+## How it's built
+
+Spec-first. Every module has a design doc (`docs/models.md`, `docs/loaders.md`, etc.) with locked decisions before any code was written. 106 tests cover construction, serialization, YAML normalization, schema enforcement, character limits, cross-file checks, and integration against a real Pharmax fixture.
+
+No graph building, no cross-referencing, no governance. That's Haxaml's job. framesdkpy is pure ingestion -- load, validate, assemble, return.

framesdkpy-0.3.0/README.md

@@ -0,0 +1,65 @@
+# FrameSDK
+
+The Python SDK for [FRAME](https://github.com/haxsysgit/FRAME) -- a typed project-context architecture for AI-assisted development.
+
+When you switch coding agents, the project forgets itself. Not its code -- the code is fine. But the *understanding*. The rules you agreed on. The decisions you made and why. The checks that matter. Things previous agents touched or broke.
+
+FRAME gives the project a typed shape that agents and tools read consistently. framesdkpy is how Python tools read that shape.
+
+## What it does
+
+Takes a `.haxaml/` directory with 5 YAML files and returns a typed `FRAME` object:
+
+```python
+from framesdkpy import load_frame
+
+frame = load_frame(".haxaml/")
+frame.facts.profile.name          # "Pharmax"
+frame.rules.governance_level      # "strict"
+frame.map.entrypoints[0].path     # "Backend/main.py"
+frame.expect.checks["backend_tests"].pass_condition  # "exit_code == 0"
+```
+
+Every downstream tool -- Haxaml, a CLI, a CI pipeline -- gets the same shaped answer. Cross-language SDKs return the same JSON shape.
+
+## Install
+
+```bash
+uv add framesdkpy
+# or
+pip install framesdkpy
+```
+
+Requires Python 3.11+. Three dependencies: PyYAML, jsonschema, referencing. That's it. No Pydantic, no heavy framework.
+
+## What's in the box
+
+- **loaders** -- `load_frame()` builds a typed FRAME from 5 YAML files. Strict single-directory discovery. Schema and character limit validation at load time.
+- **models** -- 27 typed dataclasses across 7 files. One import: `from framesdkpy.models import FRAME`.
+- **validators** -- Schema, character limits, cross-file consistency. Callable independently or through the loader.
+- **translators** -- YAML to JSON with full normalization. Handles yes/True, ~/None, on/off rejection.
+
+## Usage patterns
+
+```python
+from framesdkpy import load_frame, translate_directory, validate_file
+
+# Full pipeline -- load all 5 files, validate, assemble
+frame = load_frame(".haxaml/")
+
+# Translate YAML to clean dict (normalized, but no validation)
+data = translate_directory(".haxaml/")
+
+# Validate a single file without loading the full model
+result = validate_file(".haxaml/facts.yaml")
+print(result.summary())  # "valid" or "2 error(s), 1 warning(s)"
+
+# Serialize for cross-language use
+json_string = frame.to_json()
+```
+
+## How it's built
+
+Spec-first. Every module has a design doc (`docs/models.md`, `docs/loaders.md`, etc.) with locked decisions before any code was written. 106 tests cover construction, serialization, YAML normalization, schema enforcement, character limits, cross-file checks, and integration against a real Pharmax fixture.
+
+No graph building, no cross-referencing, no governance. That's Haxaml's job. framesdkpy is pure ingestion -- load, validate, assemble, return.

framesdkpy-0.3.0/docs/loaders.md

@@ -0,0 +1,193 @@
+# FrameSDK Loaders -- Specification
+
+**Status:** Agreed. Code follows this spec.
+**Date:** 2026-06-10
+
+---
+
+## Job
+
+A loader takes a directory path and returns a typed, validated, normalized FRAME object composed of five parts: FrameFacts, FrameRules, FrameMap, FrameExpect, FrameActs.
+
+No graph building. No cross-referencing. No governance. Pure ingestion.
+
+---
+
+## Architecture
+
+```
+frame/loaders/
+├── __init__.py           ← Public API: load_frame(dir_path)
+├── yaml_reader.py        ← Raw YAML parsing, file discovery
+├── normalizer.py         ← Type cleanup, default injection, character trimming
+└── assembler.py          ← Combines 5 parts into one FRAME
+```
+
+Flow:
+
+```
+Directory path
+  ↓
+yaml_reader verifies exactly 5 files exist: facts.yaml, rules.yaml, map.yaml, expect.yaml, acts.yaml
+  ↓
+yaml_reader parses each into raw Python dicts
+  ↓
+normalizer cleans each dict:
+  -- Trims strings to maxLength (core fields error, advisory fields warn)
+  -- Replaces YAML weirdness (null → None, yes → True, 123 → 123)
+  -- Injects defaults for optional fields
+  -- Flags missing required core fields
+  ↓
+assembler validates cross-file consistency:
+  -- All schema_version fields match
+  -- All file/role fields match their expected values
+  ↓
+assembler builds FRAME:
+  -- FRAME.facts: FrameFacts
+  -- FRAME.rules: FrameRules
+  -- etc.
+  ↓
+Returns FRAME
+```
+
+---
+
+## Decisions
+
+### D1: Validation at load time (split enforcement)
+
+Core governance fields (ids, names, rules, checks, command_refs, pass_conditions) are validated and enforced at load time. Load fails if they're missing or invalid.
+
+Descriptive/advisory fields (code_style, git, architecture notes, environment descriptions) are validated and warned at load time. Load succeeds but logs warnings.
+
+### D2: Character limits -- error for core, warn for advisory
+
+Core fields exceeding maxLength → load fails with clear error.
+Advisory fields exceeding maxLength → load succeeds, warning emitted.
+
+### D3: Strict single-directory discovery
+
+The loader receives exactly ONE directory path. It looks inside that directory for exactly 5 files: facts.yaml, rules.yaml, map.yaml, expect.yaml, acts.yaml.
+
+It NEVER:
+- Searches parent directories
+- Searches sibling directories
+- Picks up individual scattered files
+- Does fuzzy matching on filenames
+
+If any file is missing → load fails.
+If the directory doesn't exist → load fails.
+If extra YAML files exist in the directory → they are ignored (not an error).
+
+The caller controls where FRAME lives. The loader doesn't guess.
+
+### D4: Dataclasses, not Pydantic
+
+The returned models use Python dataclasses. Validation happens at load time, not at model instantiation. Dataclasses are pure typed carriers -- fast, zero-dependency, readable.
+
+### D5: Five distinct typed parts
+
+```
+FRAME
+├── facts: FrameFacts
+├── rules: FrameRules
+├── map: FrameMap
+├── expect: FrameExpect
+└── acts: FrameActs
+```
+
+Not a generic "FrameDocument" with optional nullable parts. Each part is a distinct model class with its own fields.
+
+### D6: Return typed dataclasses that serialize to clean JSON
+
+Internal: Python tools (Haxaml, CLIs) use typed dot access (`frame.facts.profile.name`).
+
+External: Cross-language tools consume JSON (`frame.to_dict()`, `frame.to_json()`).
+
+The JSON shape is the cross-language contract. The dataclasses are the Python binding. frame-js returns the same JSON shape. Any tool can switch SDKs without changing how it reads data.
+
+---
+
+## Data model
+
+```python
+@dataclass(slots=True)
+class FrameFacts:
+    profile: dict
+    classification: dict | None
+    technology: dict | None
+    architecture: dict | None
+    environments: dict | None
+    persistence: dict | None
+    sources: list[dict]
+    quirks: list[dict]
+    open_questions: list[dict]
+
+@dataclass(slots=True)
+class FrameRules:
+    governance_level: str
+    rules: list[dict]
+    policies: list[dict]
+    commands: dict
+    code_style: dict | None
+    git: dict | None
+    donts: list[dict]
+    ask_first: list[dict]
+    hints: list[dict]
+
+@dataclass(slots=True)
+class FrameMap:
+    structure: str | None
+    roots: dict | None
+    groups: list[dict]
+    paths: list[dict]
+    entrypoints: list[dict]
+    managed_paths: list[dict]
+    unmapped_paths: list[dict]
+
+@dataclass(slots=True)
+class FrameExpect:
+    outcomes: dict | None
+    must_hold: list[dict]
+    checks: dict | None
+    done_when: dict | None
+    proof: list[dict]
+    handoff: dict | None
+
+@dataclass(slots=True)
+class FrameActs:
+    summary: str | None
+    runs: list[dict]
+    blockers: list[dict]
+    handoff: dict | None
+
+@dataclass(slots=True)
+class FRAME:
+    facts: FrameFacts
+    rules: FrameRules | None
+    map: FrameMap | None
+    expect: FrameExpect | None
+    acts: FrameActs | None
+```
+
+---
+
+## Public API
+
+```python
+from framesdkpy.loaders import load_frame
+
+# Returns FRAME or raises FrameLoadError
+frame: FRAME = load_frame("/path/to/.haxaml")
+
+# Each part is a typed model
+print(frame.facts.profile["name"])
+print(frame.rules.commands["backend_tests"]["run"])
+print(frame.expect.checks["workflow_smoke"]["pass_condition"])
+```
+
+---
+
+### Decision D6.5: Assembler lives inside loaders, not a separate package
+
+The assembler builds the FRAME object from 5 validated dicts. It is tightly coupled to the loader's pipeline -- it only runs after loading and validation. Spinning it into its own package creates an abstraction nobody needs. Tools call `load_frame()`, not `assemble_frame()`. The pipeline is one cohesive flow: load -> validate -> normalize -> assemble -> return.