framesdkpy 0.3.0__py3-none-any.whl

framesdkpy/validators/limits_validator.py

@@ -0,0 +1,169 @@
+"""Character limit validator -- enforces maxLength on FRAME fields.
+
+Core governance fields (ids, names, rules, checks, command_refs, pass_conditions)
+are enforced -- exceeding their maxLength blocks the load.
+
+Advisory/descriptive fields (code_style, git, architecture notes, environment
+descriptions) are warned -- the load continues but the caller sees the warning.
+
+Character limits are defined in the finalized schema. This validator checks them.
+"""
+
+from __future__ import annotations
+
+from framesdkpy.validators.result import ValidationResult
+
+
+# ---------------------------------------------------------------------------
+# Field limit registry
+# ---------------------------------------------------------------------------
+# Each entry: (dotted_path, max_chars, enforced_or_advisory)
+# Core governance fields: enforced (error if exceeded)
+# Descriptive blocks: advisory (warning if exceeded)
+
+_FIELD_LIMITS: list[tuple[str, int, str]] = [
+    # Core governance fields -- enforced
+    ("*.id", 100, "enforced"),
+    ("*.name", 100, "enforced"),
+    ("facts.profile.name", 100, "enforced"),
+    ("facts.profile.summary", 300, "enforced"),
+    ("facts.sources[].id", 100, "enforced"),
+    ("facts.sources[].path", 200, "enforced"),
+    ("facts.quirks[].id", 100, "enforced"),
+    ("facts.open_questions[].id", 100, "enforced"),
+    ("rules.rules[].id", 100, "enforced"),
+    ("rules.policies[].id", 100, "enforced"),
+    ("rules.donts[].id", 100, "enforced"),
+    ("rules.ask_first[].id", 100, "enforced"),
+    ("rules.hints[].id", 100, "enforced"),
+    ("rules.commands.*.run", 500, "enforced"),
+    ("rules.commands.*.purpose", 300, "enforced"),
+    ("map.groups[].id", 100, "enforced"),
+    ("map.groups[].label", 150, "enforced"),
+    ("map.groups[].paths[]", 300, "enforced"),
+    ("map.entrypoints[].id", 100, "enforced"),
+    ("expect.must_hold[].id", 100, "enforced"),
+    ("expect.checks.*.name", 100, "enforced"),
+    ("expect.checks.*.command_ref", 200, "enforced"),
+    ("expect.checks.*.pass_condition", 200, "enforced"),
+    ("expect.proof[].id", 100, "enforced"),
+    ("acts.runs[].id", 100, "enforced"),
+    ("acts.runs[].actor", 100, "enforced"),
+    ("acts.blockers[].id", 100, "enforced"),
+
+    # Advisory blocks -- warned
+    ("facts.architecture.summary", 500, "advisory"),
+    ("facts.architecture.*", 500, "advisory"),
+    ("facts.technology.*", 100, "advisory"),
+    ("facts.sources[].purpose", 300, "advisory"),
+    ("facts.quirks[].description", 200, "advisory"),
+    ("facts.quirks[].why", 300, "advisory"),
+    ("facts.open_questions[].question", 300, "advisory"),
+    ("facts.open_questions[].context", 300, "advisory"),
+    ("rules.rules[].rule", 500, "advisory"),
+    ("rules.policies[].name", 150, "advisory"),
+    ("rules.policies[].rule", 500, "advisory"),
+    ("rules.donts[].rule", 300, "advisory"),
+    ("rules.ask_first[].trigger", 300, "advisory"),
+    ("rules.ask_first[].reason", 300, "advisory"),
+    ("rules.hints[].hint", 300, "advisory"),
+    ("rules.code_style", 1000, "advisory"),
+    ("rules.git", 1000, "advisory"),
+    ("map.structure", 800, "advisory"),
+    ("map.paths[].path", 200, "advisory"),
+    ("map.paths[].purpose", 300, "advisory"),
+    ("map.entrypoints[].path", 200, "advisory"),
+    ("map.managed_paths[].path", 200, "advisory"),
+    ("expect.outcomes.*.summary", 300, "advisory"),
+    ("expect.must_hold[].statement", 300, "advisory"),
+    ("expect.checks.*.what", 300, "advisory"),
+    ("expect.checks.*.how", 200, "advisory"),
+    ("expect.proof[].description", 300, "advisory"),
+    ("acts.summary", 500, "advisory"),
+    ("acts.runs[].goal", 300, "advisory"),
+    ("acts.runs[].input_summary", 300, "advisory"),
+    ("acts.runs[].output_summary", 300, "advisory"),
+    ("acts.runs[].checks[].reason", 200, "advisory"),
+    ("acts.blockers[].description", 300, "advisory"),
+]
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def validate_limits(data: dict, file_stem: str) -> ValidationResult:
+    """Check character limits on all fields in a FRAME data dict.
+
+    Walks the dict tree, matches each value against the field limit registry,
+    and reports any violations.
+    """
+    result = ValidationResult()
+    _walk_and_check(data, file_stem, result)
+    return result
+
+
+def _walk_and_check(data, path: str, result: ValidationResult):
+    """Recursively walk a dict and check field limits."""
+    if isinstance(data, dict):
+        for key, value in data.items():
+            current_path = f"{path}.{key}"
+            _check_value(value, current_path, result)
+            _walk_and_check(value, current_path, result)
+    elif isinstance(data, list):
+        for i, item in enumerate(data):
+            current_path = f"{path}[{i}]"
+            _check_value(item, current_path, result)
+            _walk_and_check(item, current_path, result)
+
+
+def _check_value(value, path: str, result: ValidationResult):
+    """Check a single value against the limit registry."""
+    if not isinstance(value, str):
+        return
+
+    # Find matching limit rules for this path
+    for pattern, max_chars, severity in _FIELD_LIMITS:
+        if not _path_matches(path, pattern):
+            continue
+
+        if len(value) > max_chars:
+            msg = f"Field exceeds maxLength of {max_chars} chars (got {len(value)})"
+            if severity == "enforced":
+                result.add_error(
+                    path=path, message=msg, code="limit_exceeded",
+                    expected=f"maxLength: {max_chars}", actual=f"length: {len(value)}",
+                )
+            else:
+                result.add_warning(path=path, message=msg, code="limit_advisory")
+            break  # First match wins -- don't report the same field twice
+
+
+def _path_matches(actual_path: str, pattern: str) -> bool:
+    """Check if a dot-separated path matches a pattern with * and [] wildcards.
+
+    Pattern: 'facts.profile.name' matches exactly.
+    Pattern: 'facts.sources[].id' matches any index: 'facts.sources[0].id'.
+    Pattern: 'rules.commands.*.run' matches any command name.
+    Pattern: 'facts.architecture.*' matches any architecture sub-field.
+    Pattern: '*.id' matches any top-level field ending in '.id'.
+    """
+    # Normalize array indices: replace [0], [1], etc. with []
+    import re
+    actual_normalized = re.sub(r'\[\d+\]', '[]', actual_path)
+
+    # Split both paths into segments
+    actual_segs = actual_normalized.split(".")
+    pattern_segs = pattern.split(".")
+
+    if len(actual_segs) != len(pattern_segs):
+        return False
+
+    for a, p in zip(actual_segs, pattern_segs):
+        if p == "*":
+            continue  # Wildcard matches any segment
+        if a != p:
+            return False
+
+    return True

framesdkpy/validators/result.py

@@ -0,0 +1,100 @@
+"""Validation result objects -- returned by all validators.
+
+Validators never raise exceptions for validation failures. They return
+ValidationResult objects. The caller decides: abort, fix and retry,
+or continue with warnings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class ValidationError:
+    """A blocking validation failure. Must be fixed before loading."""
+
+    path: str
+    """Dotted path to the failing field, e.g. 'facts.profile.name'."""
+
+    message: str
+    """Human-readable explanation of what went wrong."""
+
+    code: str
+    """Machine-readable code: 'missing_required', 'type_error', 'enum_error', 'limit_exceeded'."""
+
+    expected: str | None = None
+    """What was expected, e.g. 'string', 'maxLength: 100'."""
+
+    actual: str | None = None
+    """What was found, e.g. 'int', 'length: 245'."""
+
+
+@dataclass(slots=True)
+class ValidationWarning:
+    """A non-blocking issue. Load continues but the caller should know."""
+
+    path: str
+    """Dotted path to the field with the warning."""
+
+    message: str
+    """Human-readable explanation."""
+
+    code: str
+    """Machine-readable code: 'missing_optional', 'limit_advisory', 'unknown_field'."""
+
+
+@dataclass(slots=True)
+class ValidationResult:
+    """Aggregate result from all validators in the pipeline.
+
+    is_valid() returns True if there are zero blocking errors.
+    is_clean() returns True if there are no errors AND no warnings.
+    merge() combines results from multiple validators into one.
+    """
+
+    errors: list[ValidationError] = field(default_factory=list)
+    """Blocking errors. The load cannot proceed until these are fixed."""
+
+    warnings: list[ValidationWarning] = field(default_factory=list)
+    """Non-blocking warnings. The load proceeds but the caller sees these."""
+
+    def is_valid(self) -> bool:
+        """True if no blocking errors. Warnings don't block."""
+        return len(self.errors) == 0
+
+    def is_clean(self) -> bool:
+        """True if no errors AND no warnings."""
+        return len(self.errors) == 0 and len(self.warnings) == 0
+
+    def merge(self, other: ValidationResult) -> ValidationResult:
+        """Combine results from multiple validators."""
+        return ValidationResult(
+            errors=self.errors + other.errors,
+            warnings=self.warnings + other.warnings,
+        )
+
+    def add_error(self, path: str, message: str, code: str,
+                  expected: str | None = None, actual: str | None = None) -> None:
+        """Convenience: add a blocking error."""
+        self.errors.append(ValidationError(
+            path=path, message=message, code=code,
+            expected=expected, actual=actual,
+        ))
+
+    def add_warning(self, path: str, message: str, code: str) -> None:
+        """Convenience: add a non-blocking warning."""
+        self.warnings.append(ValidationWarning(
+            path=path, message=message, code=code,
+        ))
+
+    def summary(self) -> str:
+        """One-line summary for logging."""
+        parts = []
+        if self.errors:
+            parts.append(f"{len(self.errors)} error(s)")
+        if self.warnings:
+            parts.append(f"{len(self.warnings)} warning(s)")
+        if not parts:
+            return "valid"
+        return ", ".join(parts)

framesdkpy/validators/schema_validator.py

@@ -0,0 +1,152 @@
+"""Schema validator -- validates FRAME YAML data against JSON Schema definitions.
+
+Uses jsonschema library. Fails on type errors, missing required fields, enum
+violations, const violations, and unknown fields rejected by closed schema
+objects.
+
+Cross-file $ref links (./frame.schema.json) are resolved locally from the
+schemas/json/ directory -- no network requests.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError as JsonschemaError
+from referencing import Registry, Resource
+
+from framesdkpy.validators.result import ValidationResult
+
+
+# ---------------------------------------------------------------------------
+# Schema loading with local $ref resolution
+# ---------------------------------------------------------------------------
+
+def _schemas_dir() -> Path:
+    """Locate the schemas directory bundled with the package."""
+    this_file = Path(__file__).resolve()
+    # frame/validators/schema_validator.py → frame/validators → frame/
+    package_root = this_file.parent.parent
+    schemas = package_root / "schemas"
+    if not schemas.is_dir():
+        raise FileNotFoundError(
+            f"FRAME schemas directory not found at {schemas}. "
+            f"Expected framesdkpy/schemas/ in the FrameSDK package."
+        )
+    return schemas
+
+
+# Pre-load all schemas into a local registry so cross-file $ref links resolve
+# without network requests. Each schema gets registered under its $id URI.
+def _build_registry() -> Registry:
+    """Load all 6 JSON schemas into a referencing.Registry for local $ref resolution."""
+    resources: list[tuple[str, Resource]] = []
+    schemas_dir = _schemas_dir()
+    for schema_file in sorted(schemas_dir.glob("*.schema.json")):
+        schema = json.loads(schema_file.read_text())
+        schema_uri = schema.get("$id", "")
+        if schema_uri:
+            resources.append((schema_uri, Resource.from_contents(schema)))
+    return Registry().with_resources(resources)
+
+
+# Build once at module load time
+_SCHEMA_REGISTRY = _build_registry()
+
+
+def _load_validator(file_stem: str) -> Draft202012Validator:
+    """Load a FRAME JSON Schema and return a validator with local $ref resolution."""
+    schema_path = _schemas_dir() / f"{file_stem}.schema.json"
+    if not schema_path.exists():
+        raise FileNotFoundError(f"Schema file not found: {schema_path}")
+    schema = json.loads(schema_path.read_text())
+    return Draft202012Validator(schema, registry=_SCHEMA_REGISTRY)
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def validate_against_schema(data: dict, file_stem: str) -> ValidationResult:
+    """Validate FRAME data against its JSON Schema.
+
+    Args:
+        data: Clean dict from the translator (YAML quirks already resolved).
+        file_stem: One of 'facts', 'rules', 'map', 'expect', 'acts'.
+
+    Returns:
+        ValidationResult with errors for type/enum/required violations,
+        warnings for missing optional fields.
+    """
+    result = ValidationResult()
+    validator = _load_validator(file_stem)
+
+    # Collect errors manually so we can classify by code
+    for e in validator.iter_errors(data):
+        path = ".".join(str(p) for p in e.absolute_path) if e.absolute_path else "$"
+        code = _map_error_code(e)
+
+        if code in (
+            "missing_required",
+            "type_error",
+            "enum_error",
+            "const_error",
+            "unknown_field",
+            "schema_error",
+        ):
+            result.add_error(
+                path=path or file_stem,
+                message=e.message,
+                code=code,
+                expected=str(e.validator_value) if e.validator_value else None,
+                actual=str(e.instance)[:200] if e.instance is not None else None,
+            )
+        else:
+            result.add_warning(path=path or file_stem, message=e.message, code=code)
+
+    return result
+
+
+def _map_error_code(error: JsonschemaError) -> str:
+    """Map a jsonschema error to our validation code system."""
+    validator = error.validator
+    if validator == "required":
+        return "missing_required"
+    if validator in ("type", "pattern", "format"):
+        return "type_error"
+    if validator == "enum":
+        return "enum_error"
+    if validator == "const":
+        return "const_error"
+    if validator == "additionalProperties":
+        return "unknown_field"
+    if validator == "maxLength":
+        return "limit_exceeded"
+    return "schema_error"  # Catch-all for unexpected validation failures
+
+
+# ---------------------------------------------------------------------------
+# Convenience: validate a YAML file directly
+# ---------------------------------------------------------------------------
+
+
+def validate_yaml_file(file_path: str | Path) -> ValidationResult:
+    """Validate a single YAML FRAME file against its schema.
+
+    Parses YAML, normalizes quirks, then validates.
+    """
+    path = Path(file_path)
+    yaml_data = yaml.safe_load(path.read_text())
+    if not yaml_data or not isinstance(yaml_data, dict):
+        result = ValidationResult()
+        result.add_error(str(path), "File is empty or not a YAML object", "type_error")
+        return result
+
+    stem = path.stem  # 'facts' from 'facts.yaml'
+    from framesdkpy.translators.normalizer import normalize_dict
+    clean = normalize_dict(yaml_data)
+    return validate_against_schema(clean, stem)

framesdkpy-0.3.0.dist-info/METADATA

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

@@ -0,0 +1,29 @@
+framesdkpy/__init__.py,sha256=O6zfAF_uI344COwKg_KSQtsPWe0LhufRmbR1C3vTVAE,882
+framesdkpy/loaders/__init__.py,sha256=L7lo1Z-AKuMaJ32viOE-2yfrRs9KOTUKucKsQChTAAI,2584
+framesdkpy/loaders/assembler.py,sha256=UZm25BvnvJxPYjX111lwFTjUiiTrwdMZAhA0sKITn_Q,8374
+framesdkpy/loaders/yaml_reader.py,sha256=ZLAaJK2XjCBT7xeu6z0lM1xWv7FJUmoza9qP5KVTiyM,2012
+framesdkpy/models/__init__.py,sha256=GmRM-g-MS4Xkjc8DMMRytmg47JS8mOsLSH9fv5Jqa30,1657
+framesdkpy/models/acts_model.py,sha256=ZlrYagsp1NBgR88Oa2wIWiZciyjwNTc7Wa7mGoEf5Fo,4641
+framesdkpy/models/base.py,sha256=_5HIzG72Z-ojh52IGVx18Vo-3pjnlQe7pYZaOFJ2MIY,2505
+framesdkpy/models/expect_model.py,sha256=JsgthOvyuvKPqXH9DdYs1l3Kizq0T3dC66FCj1Avh04,4077
+framesdkpy/models/facts_model.py,sha256=rarijLCKdXOwxu1ysOFfoVTHA0XYNt6AUAhQkbayoko,5241
+framesdkpy/models/frame_model.py,sha256=sT0RvMBaAmJeLycQgU__vmMCgWtpXfxbayZAPWyUMP0,1466
+framesdkpy/models/map_model.py,sha256=-_NT9esHzHicsnXAwVVvLzjIPCcfV6WokcTBDHZW_Mg,4889
+framesdkpy/models/rules_model.py,sha256=-OAh8nUXzDi_M_rU61kEYk3Ol8x9JgKATOn1BwuMw3o,5511
+framesdkpy/schemas/acts.schema.json,sha256=SaRwbOS3FAuJg1gby54nX55QW5t2nHvoekiMkjo0bso,4228
+framesdkpy/schemas/expect.schema.json,sha256=rbXJHSL7j898zafkGlDVwtxLeLixZ3DKnRl2BOCOF5o,3766
+framesdkpy/schemas/facts.schema.json,sha256=As5SY7bTYxds8VoNExMkMx41yTSc4cTloMGmiuNR_xY,6011
+framesdkpy/schemas/frame.schema.json,sha256=MaF3dp5TPUL-wlS3FGheWNTC7lmqJTjFS-KJXzinGpE,3211
+framesdkpy/schemas/map.schema.json,sha256=jOTyE6fQ2MsB04t4vrsy3jE9QgLDsKG-EHwtL7bRRZY,4154
+framesdkpy/schemas/rules.schema.json,sha256=C2sRt3__uglo9JuL6UUJ9dinI84xsxTNGisckwqnOiQ,4941
+framesdkpy/translators/__init__.py,sha256=GWVGQMsR1ipn0wUmvp_MagC2pvMAx5I9ulS6fINsJG0,653
+framesdkpy/translators/normalizer.py,sha256=EE5OO2974trhezVx6kt1m8aBTn7strLoLUAN8VN0QFM,3710
+framesdkpy/translators/yaml_to_json.py,sha256=k_TxQ3FBjGRcRJzP7qPOgU0YzyJwQhc1i-YO-ml4NmY,2893
+framesdkpy/validators/__init__.py,sha256=Ac4v6hEiJK8fnFKTrOg5aIVGOn72Gt80aJiwu8DKaaU,2406
+framesdkpy/validators/cross_file_validator.py,sha256=K7IRhSBPQaEZDG6cM_gwYwKCQZuVRObw_LwJeqpTvqU,2738
+framesdkpy/validators/limits_validator.py,sha256=q8FNWRGdKQ5x4iUokZCOdgCMVfiVXe4sPv11n33xXu8,6817
+framesdkpy/validators/result.py,sha256=UPc8LUUnka84TqWjUAyXr9Q3IjJNrB7jc4t_1g1mC-8,3306
+framesdkpy/validators/schema_validator.py,sha256=fVUw0nzt3KkFo6_CdVCLGDf8iATtEArNZ2quPOwZy34,5581
+framesdkpy-0.3.0.dist-info/METADATA,sha256=BO3erz3B60pA1SPW4KlKqxQxl9EOf3UEQbhY7Q2OwcU,3707
+framesdkpy-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+framesdkpy-0.3.0.dist-info/RECORD,,

framesdkpy-0.3.0.dist-info/WHEEL

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