framesdkpy 0.3.0__py3-none-any.whl

framesdkpy/__init__.py

@@ -0,0 +1,33 @@
+"""FRAME Python SDK v0.3.0.
+
+The stable Python interface for reading FRAME project context files.
+Tools should import from this package root when they only need the public API.
+"""
+
+from framesdkpy.loaders import FrameLoadError, load_frame
+from framesdkpy.models import FRAME, FrameActs, FrameExpect, FrameFacts, FrameMap, FrameRules
+from framesdkpy.translators import (
+    translate_directory,
+    translate_file,
+    translate_to_dict,
+    translate_to_json_string,
+)
+from framesdkpy.validators import ValidationResult, validate_file, validate_frame
+
+__all__ = [
+    "FRAME",
+    "FrameFacts",
+    "FrameRules",
+    "FrameMap",
+    "FrameExpect",
+    "FrameActs",
+    "load_frame",
+    "FrameLoadError",
+    "validate_frame",
+    "validate_file",
+    "ValidationResult",
+    "translate_file",
+    "translate_directory",
+    "translate_to_dict",
+    "translate_to_json_string",
+]

framesdkpy/loaders/__init__.py

@@ -0,0 +1,79 @@
+"""FRAME loader -- reads YAML from a directory and returns a typed FRAME object.
+
+The full pipeline: discover → parse → normalize → validate → assemble → return.
+
+Public API:
+    load_frame(".haxaml/") → FRAME
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from framesdkpy.loaders.yaml_reader import discover_frame_dir, read_raw_yaml
+from framesdkpy.loaders.assembler import assemble_frame, FrameLoadError
+from framesdkpy.translators.normalizer import normalize_dict
+from framesdkpy.validators import validate_against_schema, validate_limits
+
+
+def load_frame(dir_path: str | Path) -> "FRAME":
+    """Load all 5 FRAME YAML files from a directory and return a typed FRAME object.
+
+    Pipeline:
+    1. Discover 5 files in the directory (strict -- all must be present)
+    2. Parse raw YAML into dicts
+    3. Normalize each dict (YAML quirks → clean types)
+    4. Validate each dict against JSON Schema + character limits
+    5. Assemble into a typed FRAME object (cross-file checks, model construction)
+
+    Raises:
+        FileNotFoundError: Directory doesn't exist or a file is missing.
+        FrameLoadError: Validation failed (schema, limits, or cross-file).
+
+    Returns:
+        FRAME with facts populated and optional other parts.
+    """
+    from framesdkpy.models.frame_model import FRAME
+
+    # 1. Discover
+    files = discover_frame_dir(dir_path)
+
+    # 2. Parse raw YAML
+    raw = read_raw_yaml(files)
+
+    # 3-4. Normalize + validate each file
+    validated: dict[str, dict] = {}
+    all_errors: list = []
+    all_warnings: list = []
+
+    for stem, raw_dict in raw.items():
+        clean = normalize_dict(raw_dict)
+
+        # Schema validation
+        schema_result = validate_against_schema(clean, stem)
+        if not schema_result.is_valid():
+            all_errors.extend(schema_result.errors)
+        all_warnings.extend(schema_result.warnings)
+
+        # Character limit validation
+        limits_result = validate_limits(clean, stem)
+        if not limits_result.is_valid():
+            all_errors.extend(limits_result.errors)
+        all_warnings.extend(limits_result.warnings)
+
+        validated[stem] = clean
+
+    # Block on any validation errors
+    if all_errors:
+        raise FrameLoadError(
+            f"Validation failed with {len(all_errors)} error(s): "
+            + "; ".join(e.message for e in all_errors[:5]),
+            errors=all_errors,
+            warnings=all_warnings,
+        )
+
+    # 5. Assemble (includes cross-file check)
+    return assemble_frame(validated)
+
+
+__all__ = ["load_frame", "FrameLoadError"]

framesdkpy/loaders/assembler.py

@@ -0,0 +1,217 @@
+"""Assembler -- builds a typed FRAME object from 5 validated and normalized dicts.
+
+Runs cross-file consistency checks, then constructs the five typed models
+and composes them into one FRAME object.
+"""
+
+from __future__ import annotations
+
+from framesdkpy.models.frame_model import FRAME
+from framesdkpy.models.facts_model import FrameFacts, Profile, Architecture, Technology, Source, Quirk, OpenQuestion
+from framesdkpy.models.rules_model import FrameRules, Policy, CoreRule, Command, Dont, AskFirst, Hint
+from framesdkpy.models.map_model import FrameMap, Group, PathEntry, Entrypoint, ManagedPath, UnmappedPath
+from framesdkpy.models.expect_model import FrameExpect, MustHold, Check, Proof
+from framesdkpy.models.acts_model import FrameActs, Run, RunCheck, Blocker
+
+from framesdkpy.validators.cross_file_validator import validate_cross_file
+
+
+class FrameLoadError(ValueError):
+    """Raised when a validated FRAME directory cannot be assembled.
+
+    Contains the validation result with all errors that prevented assembly.
+    """
+
+    def __init__(self, message: str, errors: list, warnings: list):
+        self.errors = errors
+        self.warnings = warnings
+        super().__init__(message)
+
+
+# ---------------------------------------------------------------------------
+# Sub-model constructors -- each converts a normalized dict to a typed model
+# ---------------------------------------------------------------------------
+
+
+from dataclasses import fields as dc_fields
+
+def _strip_extra(data: dict, model_class) -> dict:
+    """Keep only keys that match the model's field names."""
+    field_names = {f.name for f in dc_fields(model_class)}
+    return {k: v for k, v in data.items() if k in field_names}
+
+
+def _build_facts(data: dict) -> FrameFacts:
+    prof = data.get("profile", {})
+    arch = data.get("architecture", {})
+    tech = data.get("technology")
+
+    return FrameFacts(
+        frame=data["frame"],
+        profile=Profile(
+            name=prof["name"],
+            summary=prof["summary"],
+            repo_shape=prof.get("repo_shape"),
+            delivery_family=prof.get("delivery_family"),
+        ),
+        architecture=Architecture(
+            summary=arch["summary"],
+            backend_layers=arch.get("backend_layers"),
+            frontend_layers=arch.get("frontend_layers"),
+            data_flow=arch.get("data_flow"),
+            deployment_topology=arch.get("deployment_topology"),
+        ),
+        technology=Technology(
+            language=tech.get("language") if tech else None,
+            framework=tech.get("framework") if tech else None,
+            database=tech.get("database") if tech else None,
+            extensions=tech.get("extensions") if tech else None,
+        ) if tech else None,
+        sources=[Source(**_strip_extra(s, Source)) for s in data.get("sources", [])],
+        quirks=[Quirk(**_strip_extra(q, Quirk)) for q in data.get("quirks", [])],
+        open_questions=[OpenQuestion(**_strip_extra(o, OpenQuestion)) for o in data.get("open_questions", [])],
+        classification=data.get("classification"),
+        environments=data.get("environments"),
+        persistence=data.get("persistence"),
+        evidence=data.get("evidence", []),
+        links=data.get("links", []),
+    )
+
+
+def _build_rules(data: dict) -> FrameRules:
+    commands_dict: dict[str, Command] = {}
+
+    for name, cmd_data in data.get("commands", {}).items():
+        commands_dict[name] = Command(**_strip_extra(cmd_data, Command))
+
+    return FrameRules(
+        frame=data["frame"],
+        governance_level=data.get("governance_level", "normal"),
+        rules=[CoreRule(**_strip_extra(r, CoreRule)) for r in data.get("rules", [])],
+        policies=[Policy(**_strip_extra(p, Policy)) for p in data.get("policies", [])],
+        commands=commands_dict,
+        donts=[Dont(**_strip_extra(d, Dont)) for d in data.get("donts", [])],
+        ask_first=[AskFirst(**_strip_extra(a, AskFirst)) for a in data.get("ask_first", [])],
+        hints=[Hint(**_strip_extra(h, Hint)) for h in data.get("hints", [])],
+        code_style=data.get("code_style"),
+        git=data.get("git"),
+        evidence=data.get("evidence", []),
+        links=data.get("links", []),
+    )
+
+
+def _build_map(data: dict) -> FrameMap:
+    """Build FrameMap from a normalized map dict."""
+    return FrameMap(
+        frame=data["frame"],
+        structure=data.get("structure"),
+        roots=data.get("roots"),
+        groups=[Group(**_strip_extra(g, Group)) for g in data.get("groups", [])],
+        paths=[PathEntry(**_strip_extra(p, PathEntry)) for p in data.get("paths", [])],
+        entrypoints=[Entrypoint(**_strip_extra(e, Entrypoint)) for e in data.get("entrypoints", [])],
+        managed_paths=[ManagedPath(**_strip_extra(m, ManagedPath)) for m in data.get("managed_paths", [])],
+        unmapped_paths=[UnmappedPath(**_strip_extra(u, UnmappedPath)) for u in data.get("unmapped_paths", [])],
+        evidence=data.get("evidence", []),
+        links=data.get("links", []),
+    )
+
+
+def _build_expect(data: dict) -> FrameExpect:
+    """Build FrameExpect from a normalized expect dict."""
+    checks_dict: dict[str, Check] = {}
+    for name, chk_data in data.get("checks", {}).items():
+        checks_dict[name] = Check(**_strip_extra(chk_data, Check))
+
+    return FrameExpect(
+        frame=data["frame"],
+        outcomes=data.get("outcomes"),
+        must_hold=[MustHold(**_strip_extra(m, MustHold)) for m in data.get("must_hold", [])],
+        checks=checks_dict,
+        done_when=data.get("done_when"),
+        proof=[Proof(**_strip_extra(p, Proof)) for p in data.get("proof", [])],
+        handoff=data.get("handoff"),
+        evidence=data.get("evidence", []),
+        links=data.get("links", []),
+    )
+
+
+def _build_acts(data: dict) -> FrameActs:
+    """Build FrameActs from a normalized acts dict."""
+    runs: list[Run] = []
+    for run_data in data.get("runs", []):
+        # Build nested RunCheck objects
+        checks_list: list[RunCheck] = []
+        for rc_data in run_data.get("checks", []) or []:
+            checks_list.append(RunCheck(**_strip_extra(rc_data, RunCheck)))
+
+        run_data_copy = {k: v for k, v in run_data.items() if k != "checks"}
+        runs.append(Run(checks=checks_list if checks_list else None, **_strip_extra(run_data_copy, Run)))
+
+    return FrameActs(
+        frame=data["frame"],
+        summary=data.get("summary"),
+        runs=runs,
+        blockers=[Blocker(**_strip_extra(b, Blocker)) for b in data.get("blockers", [])],
+        handoff=data.get("handoff"),
+        evidence=data.get("evidence", []),
+        links=data.get("links", []),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main assembly function
+# ---------------------------------------------------------------------------
+
+
+_BUILDERS = {
+    "facts": _build_facts,
+    "rules": _build_rules,
+    "map": _build_map,
+    "expect": _build_expect,
+    "acts": _build_acts,
+}
+
+
+def assemble_frame(parts: dict[str, dict]) -> FRAME:
+    """Build a typed FRAME object from 5 validated and normalized dicts.
+
+    Runs cross-file consistency check first. Raises FrameLoadError if
+    schema versions don't match or file/role fields are inconsistent.
+
+    Args:
+        parts: Dict mapping file stem to normalized dict.
+               e.g., {"facts": {...}, "rules": {...}, ...}
+
+    Returns:
+        FRAME object with all five typed parts.
+    """
+    required_parts = {"facts", "rules", "map", "expect", "acts"}
+    missing_parts = sorted(required_parts - set(parts))
+    if missing_parts:
+        raise FrameLoadError(
+            f"Missing FRAME part(s): {', '.join(missing_parts)}",
+            errors=[],
+            warnings=[],
+        )
+
+    # Cross-file consistency must pass before assembly
+    cross_result = validate_cross_file(parts)
+    if not cross_result.is_valid():
+        raise FrameLoadError(
+            f"Cross-file validation failed: {cross_result.summary()}",
+            errors=cross_result.errors,
+            warnings=cross_result.warnings,
+        )
+
+    built = {}
+    for stem in ["facts", "rules", "map", "expect", "acts"]:
+        builder = _BUILDERS[stem]
+        built[stem] = builder(parts[stem])
+
+    return FRAME(
+        facts=built["facts"],
+        rules=built["rules"],
+        map=built["map"],
+        expect=built["expect"],
+        acts=built["acts"],
+    )

framesdkpy/loaders/yaml_reader.py

@@ -0,0 +1,57 @@
+"""YAML reader -- discovers and parses FRAME YAML files from a directory.
+
+Strict single-directory discovery: exactly 5 files must be present.
+No fuzzy matching, no parent/sibling search, no scattered file pickup.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+# All 5 are discovered. Facts and Rules are required for any project.
+# Map is required if the repo has structure; empty repos can omit it.
+# Expect and Acts grow over time.
+_EXPECTED_FILES = ["facts", "rules", "map", "expect", "acts"]
+
+
+def discover_frame_dir(dir_path: str | Path) -> dict[str, Path]:
+    """Verify exactly 5 FRAME YAML files exist in a directory.
+
+    Returns a dict mapping file stem to resolved Path. Raises FileNotFoundError
+    if the directory doesn't exist or any expected file is missing.
+    """
+    directory = Path(dir_path).resolve()
+    if not directory.is_dir():
+        raise FileNotFoundError(f"FRAME directory not found: {directory}")
+
+    found: dict[str, Path] = {}
+    for stem in _EXPECTED_FILES:
+        yaml_path = directory / f"{stem}.yaml"
+        if not yaml_path.is_file():
+            raise FileNotFoundError(
+                f"Missing FRAME file: {stem}.yaml in {directory}. "
+                f"All 5 files (facts, rules, map, expect, acts) must be in the same directory."
+            )
+        found[stem] = yaml_path
+
+    return found
+
+
+def read_raw_yaml(file_stems: dict[str, Path]) -> dict[str, dict]:
+    """Parse YAML files into raw Python dicts.
+
+    Returns a dict mapping file stem to raw parsed dict. YAML quirks (yes→True,
+    ~→None) are handled by the normalizer downstream -- this is raw parsing only.
+    """
+    raw: dict[str, dict] = {}
+    for stem, path in file_stems.items():
+        data = yaml.safe_load(path.read_text())
+        if data is None:
+            data = {}
+        if not isinstance(data, dict):
+            raise ValueError(f"Expected YAML object in {stem}.yaml, got {type(data).__name__}")
+        raw[stem] = data
+    return raw

framesdkpy/models/__init__.py

@@ -0,0 +1,95 @@
+"""FRAME models -- typed data carriers for all five FRAME parts.
+
+Primary import for downstream tools:
+    from framesdkpy.models import FRAME, FrameFacts, FrameRules, FrameMap, FrameExpect, FrameActs
+
+Sub-models for deeper access:
+    from framesdkpy.models import Profile, Command, Check, Run, Blocker, etc.
+"""
+
+from framesdkpy.models.frame_model import FRAME
+
+from framesdkpy.models.facts_model import (
+    FrameFacts,
+    Profile,
+    Architecture,
+    Technology,
+    Source,
+    Quirk,
+    OpenQuestion,
+)
+
+from framesdkpy.models.rules_model import (
+    FrameRules,
+    Policy,
+    CoreRule,
+    Command,
+    Dont,
+    AskFirst,
+    Hint,
+)
+
+from framesdkpy.models.map_model import (
+    FrameMap,
+    Group,
+    PathEntry,
+    Entrypoint,
+    ManagedPath,
+    UnmappedPath,
+)
+
+from framesdkpy.models.expect_model import (
+    FrameExpect,
+    MustHold,
+    Check,
+    Proof,
+)
+
+from framesdkpy.models.acts_model import (
+    FrameActs,
+    Run,
+    RunCheck,
+    Blocker,
+)
+
+from framesdkpy.models.base import FrameBaseModel
+
+# Everything a downstream tool needs, one import away
+__all__ = [
+    # Top-level
+    "FRAME",
+    "FrameBaseModel",
+    # Facts
+    "FrameFacts",
+    "Profile",
+    "Architecture",
+    "Technology",
+    "Source",
+    "Quirk",
+    "OpenQuestion",
+    # Rules
+    "FrameRules",
+    "Policy",
+    "CoreRule",
+    "Command",
+    "Dont",
+    "AskFirst",
+    "Hint",
+    # Map
+    "FrameMap",
+    "Group",
+    "PathEntry",
+    "Entrypoint",
+    "ManagedPath",
+    "UnmappedPath",
+    # Expect
+    "FrameExpect",
+    "MustHold",
+    "Check",
+    "Proof",
+    # Acts
+    "FrameActs",
+    "Run",
+    "RunCheck",
+    "Blocker",
+]

framesdkpy/models/acts_model.py

@@ -0,0 +1,139 @@
+"""FrameActs model and sub-models -- checked activity record.
+
+Mirrors schemas/json/acts.schema.json exactly.
+Acts is run history -- what went in, what came out, what changed, what checks ran.
+Size cap: 50KB. Exceeded → oldest runs auto-rotated to acts_archive/.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from framesdkpy.models.base import FrameBaseModel
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class RunCheck(FrameBaseModel):
+    """A check considered or executed during a single run.
+
+    Collapsed from the old checks_seen/checks_ran split into one field with status.
+    status: ran (check was executed) or skipped (considered but not applicable).
+    result: only present when status=ran. pass or fail.
+    reason: only present when status=skipped. Why it was skipped.
+    """
+
+    id: str
+    """Ref to expect.checks.<name>. This is the check that was considered or executed."""
+
+    status: str
+    """Enum: ran, skipped. ran = executed, skipped = considered but not applicable."""
+
+    result: str | None = None
+    """Enum: pass, fail. Only set when status=ran."""
+
+    reason: str | None = None
+    """Why skipped. Only set when status=skipped. maxLength: 200."""
+
+
+@dataclass(slots=True)
+class Run(FrameBaseModel):
+    """A single agent session run. Has an id for cross-referencing.
+
+    work_kind: tags for what kind of work was done (code, test, review, docs, deploy).
+    status: the overall run outcome. Pass means all checks passed.
+    Pass_with_risks means passed but with warnings. Fail means something broke.
+    Needs_clarification means the agent couldn't determine the outcome.
+    """
+
+    id: str
+    """Stable identifier. Used for cross-referencing from other Acts entries. maxLength: 100."""
+
+    actor: str
+    """Who or what did the work (agent name, model, or human). maxLength: 100."""
+
+    goal: str
+    """What the run was trying to accomplish. maxLength: 300."""
+
+    status: str
+    """Enum: pass, pass_with_risks, fail, needs_clarification."""
+
+    work_kind: list[str] | None = None
+    """Tags: code, test, review, docs, deploy."""
+
+    keywords: list[str] | None = None
+    """Topic tags for searchable retrieval."""
+
+    input_summary: str | None = None
+    """What went into the run. maxLength: 300."""
+
+    output_summary: str | None = None
+    """What came out. maxLength: 300."""
+
+    touched: list[str] | None = None
+    """Files, paths, or surfaces touched during the run."""
+
+    changed_facts: list[str] | None = None
+    """Facts that were modified during the run."""
+
+    rules_followed: list[str] | None = None
+    """Rule or policy ids that were applied."""
+
+    checks: list[RunCheck] | None = None
+    """Checks considered or executed this run. Each has status and optional result/reason."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Blocker(FrameBaseModel):
+    """Something preventing progress. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    description: str
+    """What is blocking progress. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+# ---------------------------------------------------------------------------
+# Main model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class FrameActs(FrameBaseModel):
+    """Run history -- what happened across agent sessions.
+
+    Populated from acts.yaml. Grows over time as agents work on the project.
+    Older runs auto-rotate to acts_archive/ when the file exceeds 50KB.
+    """
+
+    frame: dict = field(default_factory=dict)
+    """Shared FRAME header block. Required by every FRAME file."""
+
+    summary: str | None = None
+    """Quick overview of recent activity. maxLength: 500."""
+
+    runs: list[Run] = field(default_factory=list)
+    """Per-session run records. Each has a stable id for cross-referencing."""
+
+    blockers: list[Blocker] = field(default_factory=list)
+    """Things preventing progress. Each has a stable id."""
+
+    handoff: dict | None = None
+    """What the next agent needs to know. Free-form."""
+
+    evidence: list[dict] = field(default_factory=list)
+    """Evidence entries supporting Acts claims."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this file to other FRAME refs."""

framesdkpy/models/base.py

@@ -0,0 +1,64 @@
+"""Shared base class for all FRAME models.
+
+Provides serialization (to_dict, to_json) and developer-friendly repr.
+Every FRAME model inherits from FrameBaseModel. This ensures uniform
+output format across all five parts regardless of which tool consumes them.
+
+Null preservation: to_dict() keeps nulls in the output so the JSON shape
+is always complete. Cross-language tools (frame-js, frame-cpp) can rely
+on every key existing even if its value is null.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, fields, is_dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class FrameBaseModel:
+    """All FRAME models inherit this for uniform serialization.
+
+    Serialization preserves nulls -- if a field is None, the key appears in
+    the dict with a null value. This keeps the JSON shape consistent across
+    tools and languages.
+    """
+
+    def to_dict(self) -> dict[str, Any]:
+        """Recursive serialization to a JSON-compatible dict. Preserves nulls.
+
+        Nested FrameBaseModel instances and lists of models are handled
+        recursively. Regular dicts, lists, strings, and primitives pass through.
+        """
+        result: dict[str, Any] = {}
+        for field in fields(self):
+            value = getattr(self, field.name)
+            result[field.name] = self._serialize_value(value)
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        """Serialize to a JSON string. Passes through to_dict() first."""
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    @staticmethod
+    def _serialize_value(value: Any) -> Any:
+        """Recursively convert a value to a JSON-safe representation.
+
+        - FrameBaseModel → call to_dict()
+        - list of models → list of dicts
+        - dict → recurse into values
+        - None, str, int, float, bool → pass through
+        """
+        if isinstance(value, FrameBaseModel):
+            return value.to_dict()
+        if isinstance(value, list):
+            return [FrameBaseModel._serialize_value(item) for item in value]
+        if isinstance(value, dict):
+            return {k: FrameBaseModel._serialize_value(v) for k, v in value.items()}
+        return value  # Primitive: str, int, float, bool, None
+
+    def __repr__(self) -> str:
+        """Developer-friendly display showing class name and field count."""
+        field_names = [f.name for f in fields(self)]
+        return f"{type(self).__name__}({', '.join(field_names)})"