framesdkpy 0.3.0__py3-none-any.whl

framesdkpy/models/expect_model.py

@@ -0,0 +1,127 @@
+"""FrameExpect model and sub-models -- what must pass.
+
+Mirrors schemas/json/expect.schema.json exactly.
+The expect block feeds directly into the mechanical validator.
+checks connect to rules.commands via command_ref.
+pass_condition defines machine-parseable success criteria.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from framesdkpy.models.base import FrameBaseModel
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class MustHold(FrameBaseModel):
+    """Invariant that must remain true. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    statement: str
+    """The invariant statement. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Check(FrameBaseModel):
+    """Verification check that feeds the mechanical validator.
+
+    command_ref points to rules.commands.<name> -- the shell command to execute.
+    pass_condition is machine-parseable: 'exit_code == 0', 'stdout contains X',
+    'stdout matches REGEX', or 'file_exists PATH'.
+    """
+
+    name: str
+    """Short check name displayed in reports. maxLength: 100."""
+
+    what: str
+    """What is being checked -- human-readable explanation. maxLength: 300."""
+
+    how: str | None = None
+    """How the check works: test, build, lint, grep, manual. maxLength: 200."""
+
+    command_ref: str | None = None
+    """Ref to rules.commands.<name> for executable verification. maxLength: 200."""
+
+    pass_condition: str | None = None
+    """Machine-parseable success criteria. Examples:
+    'exit_code == 0'
+    'stdout contains BUILD SUCCESS'
+    'stdout matches ^[a-f0-9]{12}_'
+    'file_exists dist/index.html'
+    """
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Proof(FrameBaseModel):
+    """Required evidence type. Has an id for cross-referencing.
+
+    type: review (human review needed), smoke_test (quick sanity check),
+    static_check (linter/type checker), unavailable (can't verify yet).
+    """
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    type: str
+    """Fixed enum: review, smoke_test, static_check, unavailable."""
+
+    description: str
+    """What evidence is needed. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+# ---------------------------------------------------------------------------
+# Main model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class FrameExpect(FrameBaseModel):
+    """What must pass -- outcomes, invariants, checks, proof requirements.
+
+    Populated from expect.yaml. This is the contract the mechanical validator
+    enforces. checks connect to rules.commands via command_ref.
+    """
+
+    frame: dict = field(default_factory=dict)
+    """Shared FRAME header block. Required by every FRAME file."""
+
+    outcomes: dict | None = None
+    """Named expected results of work. Keys are outcome names."""
+
+    must_hold: list[MustHold] = field(default_factory=list)
+    """Invariants that must stay true. Each has a stable id."""
+
+    checks: dict[str, Check] = field(default_factory=dict)
+    """Verification checks. Key is the check name -- used as command_ref target."""
+
+    done_when: dict | None = None
+    """Completion conditions. Free-form keys."""
+
+    proof: list[Proof] = field(default_factory=list)
+    """Required evidence types. Each has a stable id."""
+
+    handoff: dict | None = None
+    """State to pass to the next session. Free-form."""
+
+    evidence: list[dict] = field(default_factory=list)
+    """Evidence entries supporting Expect claims."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this file to other FRAME refs."""

framesdkpy/models/facts_model.py

@@ -0,0 +1,163 @@
+"""FrameFacts model and sub-models -- stable project truth.
+
+Mirrors schemas/json/facts.schema.json exactly. Required fields are
+non-nullable (str, not str | None). The loader guarantees these are
+populated before model construction. Optional fields use | None.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from framesdkpy.models.base import FrameBaseModel
+
+
+# ---------------------------------------------------------------------------
+# Sub-models -- typed representations of Facts blocks
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class Profile(FrameBaseModel):
+    """Project identity. name and summary are always present."""
+
+    name: str
+    """Project name. maxLength: 100."""
+
+    summary: str
+    """One-paragraph project description. maxLength: 300."""
+
+    repo_shape: str | None = None
+    """Enum: split-backend-frontend, monorepo, single-package, monolith, microservices."""
+
+    delivery_family: str | None = None
+    """Enum: cli, web-app, mobile-app, sdk, infra-tooling, data-pipeline, etc."""
+
+
+@dataclass(slots=True)
+class Architecture(FrameBaseModel):
+    """System layout. summary is always present."""
+
+    summary: str
+    """Human-readable system layout overview. maxLength: 500."""
+
+    backend_layers: list[str] | None = None
+    """Ordered list of backend architectural layers, e.g. ['routes', 'services', 'models']."""
+
+    frontend_layers: list[str] | None = None
+    """Ordered list of frontend layers, e.g. ['views', 'stores', 'services']."""
+
+    data_flow: str | None = None
+    """Description of how data moves through the system. maxLength: 500."""
+
+    deployment_topology: str | None = None
+    """Where and how the system is deployed. maxLength: 500."""
+
+
+@dataclass(slots=True)
+class Technology(FrameBaseModel):
+    """Structured technology stack. Required fields are present when this block exists."""
+
+    language: str
+    """Primary programming language. maxLength: 100."""
+
+    framework: str
+    """Primary framework (FastAPI, Next.js, etc.). maxLength: 100."""
+
+    database: str
+    """Primary database (PostgreSQL, SQLite, etc.). maxLength: 100."""
+
+    extensions: dict | None = None
+    """Optional free-form extensions for additional tech details."""
+
+
+@dataclass(slots=True)
+class Source(FrameBaseModel):
+    """Trusted source-of-truth file. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier -- other files reference this via 'facts.sources.<id>'. maxLength: 100."""
+
+    path: str
+    """Filesystem path to the source file. maxLength: 200."""
+
+    purpose: str
+    """Why this file is a source of truth. maxLength: 300."""
+
+
+@dataclass(slots=True)
+class Quirk(FrameBaseModel):
+    """Weird project-specific thing agents must understand. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    description: str
+    """What the quirk is. maxLength: 200."""
+
+    why: str
+    """Why this quirk exists -- prevents agents from 'fixing' it. maxLength: 300."""
+
+
+@dataclass(slots=True)
+class OpenQuestion(FrameBaseModel):
+    """Thing nobody has decided yet. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    question: str
+    """The unresolved question. maxLength: 300."""
+
+    context: str
+    """Background needed to understand the question. maxLength: 300."""
+
+
+# ---------------------------------------------------------------------------
+# Main model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class FrameFacts(FrameBaseModel):
+    """Stable project truth -- what the project is, how it's built, its quirks.
+
+    Populated by the loader from facts.yaml. Required fields are non-nullable.
+    Optional blocks (environments, persistence, classification) use | None.
+    """
+
+    frame: dict
+    """Shared FRAME header block. Required by every FRAME file."""
+
+    profile: Profile
+    """Required. Every project has a name and summary."""
+
+    architecture: Architecture
+    """Required. Every project has a system layout."""
+
+    sources: list[Source] = field(default_factory=list)
+    """Trusted source-of-truth files. Each has a stable id for cross-referencing."""
+
+    quirks: list[Quirk] = field(default_factory=list)
+    """Project-specific oddities agents must understand. Each has a stable id."""
+
+    open_questions: list[OpenQuestion] = field(default_factory=list)
+    """Unresolved questions. Each has a stable id."""
+
+    classification: dict | None = None
+    """Project classification details. Free-form -- varies per project."""
+
+    technology: Technology | None = None
+    """Structured technology stack. Optional at first."""
+
+    environments: dict | None = None
+    """Per-environment configuration. Free-form keys (local, production, staging)."""
+
+    persistence: dict | None = None
+    """Database, ORM, migration, and storage details. Free-form -- varies by ORM/storage."""
+
+    evidence: list[dict] = field(default_factory=list)
+    """Evidence entries supporting Facts claims."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this file to other FRAME refs."""

framesdkpy/models/frame_model.py

@@ -0,0 +1,42 @@
+"""FRAME -- the assembled whole.
+
+Composes all five typed parts into one model. All 5 files must be present
+in the .haxaml/ directory at all times (D3: strict single-directory discovery).
+Empty files are valid -- content depth is Haxaml's concern, not the SDK's.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from framesdkpy.models.base import FrameBaseModel
+from framesdkpy.models.facts_model import FrameFacts
+from framesdkpy.models.rules_model import FrameRules
+from framesdkpy.models.map_model import FrameMap
+from framesdkpy.models.expect_model import FrameExpect
+from framesdkpy.models.acts_model import FrameActs
+
+
+@dataclass(slots=True)
+class FRAME(FrameBaseModel):
+    """The assembled FRAME object -- all five parts in one typed model.
+
+    All 5 files are required by the loader (D3). Content depth varies --
+    a new project has empty Expect and Acts. A mature project fills them.
+    The SDK validates structure and schema. Haxaml enforces content.
+    """
+
+    facts: FrameFacts
+    """Required. Stable project truth -- identity, stack, architecture, quirks."""
+
+    rules: FrameRules
+    """Required. Governance constraints, commands, policies."""
+
+    map: FrameMap
+    """Required. Where things live -- at minimum structure + roots."""
+
+    expect: FrameExpect
+    """Required. What must pass -- may be empty in early projects."""
+
+    acts: FrameActs
+    """Required. Run history -- starts empty, grows over time."""

framesdkpy/models/map_model.py

@@ -0,0 +1,157 @@
+"""FrameMap model and sub-models -- where things live in the repo.
+
+Mirrors schemas/json/map.schema.json exactly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from framesdkpy.models.base import FrameBaseModel
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class Group(FrameBaseModel):
+    """Logical grouping of paths. Supports wildcards for flexible coverage.
+
+    Groups let the map cover growing repos without requiring every new file
+    to be individually registered.
+    """
+
+    id: str
+    """Stable identifier for cross-referencing. maxLength: 100."""
+
+    label: str
+    """Human-readable group name. maxLength: 150."""
+
+    paths: list[str] = field(default_factory=list)
+    """File/directory paths in this group. Wildcards allowed (e.g. 'Backend/app/**/*.py')."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class PathEntry(FrameBaseModel):
+    """Critical individual file. Explicit path only -- no wildcards.
+
+    Optional id for cross-referencing from expect.checks or acts.runs.touched.
+    """
+
+    path: str
+    """Filesystem path. maxLength: 200."""
+
+    purpose: str
+    """Why this file is important. maxLength: 300."""
+
+    id: str | None = None
+    """Optional stable identifier. Only needed when this path is referenced from another file."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Entrypoint(FrameBaseModel):
+    """CLI, API, web, or script entry point. Always has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    path: str
+    """Filesystem path to the entry point. maxLength: 200."""
+
+    kind: str
+    """Fixed enum: cli, api, web, script."""
+
+    description: str | None = None
+    """What this entry point does. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class ManagedPath(FrameBaseModel):
+    """Path under special rule. Supports wildcards.
+
+    rule: generated (auto-generated files), config (.env, settings files),
+    immutable (migration files, lock files).
+    """
+
+    path: str
+    """Filesystem path or wildcard pattern. maxLength: 200."""
+
+    rule: str
+    """Fixed enum: generated, config, immutable."""
+
+    id: str | None = None
+    """Optional stable identifier for cross-referencing from rules.donts or expect.checks."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class UnmappedPath(FrameBaseModel):
+    """Path not yet placed in the map. Honest about gaps -- invites improvement."""
+
+    path: str
+    """Filesystem path that needs mapping. maxLength: 200."""
+
+    reason: str
+    """Why this path hasn't been mapped yet. maxLength: 200."""
+
+
+# ---------------------------------------------------------------------------
+# Main model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class FrameMap(FrameBaseModel):
+    """Where things live in the repo. Populated from map.yaml.
+
+    structure provides a quick visual overview (top block).
+    roots describe top-level directories.
+    groups provide logical groupings with wildcard support.
+    paths list critical individual files.
+    entrypoints show CLI/API/web start points.
+    managed_paths declare files under special rules.
+    unmapped_paths acknowledge gaps.
+    """
+
+    frame: dict = field(default_factory=dict)
+    """Shared FRAME header block. Required by every FRAME file."""
+
+    structure: str | None = None
+    """Quick visual overview of repo layout. Top block, maxLength: 800."""
+
+    roots: dict | None = None
+    """Top-level directory purposes. Free-form keys."""
+
+    groups: list[Group] = field(default_factory=list)
+    """Logical groupings of paths. Supports wildcards."""
+
+    paths: list[PathEntry] = field(default_factory=list)
+    """Critical individual files. Explicit paths only."""
+
+    entrypoints: list[Entrypoint] = field(default_factory=list)
+    """CLI/API/web entry points. Each has a stable id."""
+
+    managed_paths: list[ManagedPath] = field(default_factory=list)
+    """Paths under special rules. Supports wildcards."""
+
+    unmapped_paths: list[UnmappedPath] = field(default_factory=list)
+    """Paths not yet mapped. Honest about gaps."""
+
+    evidence: list[dict] = field(default_factory=list)
+    """Evidence entries supporting Map claims."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this file to other FRAME refs."""

framesdkpy/models/rules_model.py

@@ -0,0 +1,181 @@
+"""FrameRules model and sub-models -- how to work safely in this repo.
+
+Mirrors schemas/json/rules.schema.json exactly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from framesdkpy.models.base import FrameBaseModel
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class Policy(FrameBaseModel):
+    """Durable project policy (role access, lifecycle, audit, auth).
+
+    Moved from Facts to Rules -- policies are behavioral constraints,
+    not current project truth.
+    """
+
+    id: str
+    """Stable identifier for cross-referencing. maxLength: 100."""
+
+    name: str
+    """Short policy name. maxLength: 150."""
+
+    rule: str
+    """The policy rule text. maxLength: 500."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class CoreRule(FrameBaseModel):
+    """Core behavioral constraint. Has an id for cross-referencing."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    rule: str
+    """The constraint text. maxLength: 500."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Command(FrameBaseModel):
+    """Named shell command with a fixed schema.
+
+    kind: setup (install deps), verify (validation check), or run (server/interactive).
+    The mechanical validator uses kind to decide which commands to execute.
+    """
+
+    run: str
+    """Shell command to execute. maxLength: 500."""
+
+    kind: str
+    """Fixed enum: setup, verify, run."""
+
+    purpose: str
+    """Why this command exists. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Dont(FrameBaseModel):
+    """Thing you must never do. severity: critical (blocks) or warning (flags)."""
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    rule: str
+    """The forbidden action. maxLength: 300."""
+
+    severity: str = "critical"
+    """Enum: critical, warning. critical blocks the agent; warning flags it."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class AskFirst(FrameBaseModel):
+    """Trigger needing human approval before the agent proceeds.
+
+    trigger_type: file_pattern (matches against files the agent will touch)
+    or task_pattern (matches against the agent's stated task description).
+    """
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    trigger_type: str
+    """Fixed enum: file_pattern, task_pattern."""
+
+    trigger: str
+    """The pattern to match against. maxLength: 300."""
+
+    reason: str
+    """Why approval is needed. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+@dataclass(slots=True)
+class Hint(FrameBaseModel):
+    """Skill reference, known gotcha, or task-specific guidance.
+
+    Hints are not enforced -- they help the agent work faster.
+    """
+
+    id: str
+    """Stable identifier. maxLength: 100."""
+
+    hint: str
+    """The guidance text. maxLength: 300."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this entry to other FRAME refs."""
+
+
+# ---------------------------------------------------------------------------
+# Main model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class FrameRules(FrameBaseModel):
+    """How to work safely in this repo. Populated from rules.yaml.
+
+    governance_level controls enforcement strictness:
+    relaxed → agents proceed freely, ask_first is advisory
+    normal   → ask_first warns but doesn't block
+    strict   → ask_first blocks, donts enforced, validator must pass
+    """
+
+    frame: dict = field(default_factory=dict)
+    """Shared FRAME header block. Required by every FRAME file."""
+
+    governance_level: str = "normal"
+    """Enum: relaxed, normal, strict. Controls Haxaml enforcement strictness."""
+
+    rules: list[CoreRule] = field(default_factory=list)
+    """Core behavioral constraints."""
+
+    policies: list[Policy] = field(default_factory=list)
+    """Durable project policies (role access, lifecycle, audit)."""
+
+    commands: dict[str, Command] = field(default_factory=dict)
+    """Named shell commands. Key is the command name used by expect.checks.command_ref."""
+
+    donts: list[Dont] = field(default_factory=list)
+    """Things you must never do. severity determines enforcement."""
+
+    ask_first: list[AskFirst] = field(default_factory=list)
+    """Triggers needing human approval. Enforcement depends on governance_level."""
+
+    hints: list[Hint] = field(default_factory=list)
+    """Skill references, gotchas, task-specific guidance."""
+
+    code_style: dict | None = None
+    """Formatting, naming, conventions. Free-form -- varies per language. Advisory limit 1000 chars."""
+
+    git: dict | None = None
+    """Branch strategy, commit style, PR rules. Free-form -- varies per team. Advisory limit 1000 chars."""
+
+    evidence: list[dict] = field(default_factory=list)
+    """Evidence entries supporting Rules claims."""
+
+    links: list[dict] = field(default_factory=list)
+    """Typed links from this file to other FRAME refs."""