codec-cortex 0.3.2__py3-none-any.whl

cortex/templates/__init__.py

@@ -0,0 +1,8 @@
+"""Template factories for new ``.cortex`` documents."""
+
+from .minimal_glossary import build_minimal_glossary
+from .brain import build_brain
+from .skill import build_skill
+from .package import build_package
+
+__all__ = ["build_minimal_glossary", "build_brain", "build_skill", "build_package"]

cortex/templates/brain.py

@@ -0,0 +1,118 @@
+"""``brain.cortex`` template factory.
+
+Builds a Nivel 2 operative brain with:
+  - $0: minimal local glossary (autocontención)
+  - $1: IDENTITY (IDN:agent, IDN:human, DOM:workspace)
+  - $2: ACTIVE WORK (FCS:primary, OBJ:main, WRK:state, STP:next)
+  - $3: GOVERNANCE (CNST:self_contained)
+
+Mirrors Section 18.2 of SKILL.md.
+"""
+
+from __future__ import annotations
+
+
+from ..core.ast import CortexDocument, Section
+from ..core.parser import build_entry_from_value
+from ..glossary.minimal import brain_sigils
+from .minimal_glossary import build_minimal_glossary
+
+
+def build_brain(
+    name: str = "project-brain",
+    domain: str = "active work",
+    owner: str = "agent",
+    language: str = "en",
+    template: str = "standard",
+    with_diagrams: bool = False,
+) -> CortexDocument:
+    """Return a fresh ``brain.cortex`` :class:`CortexDocument`."""
+
+    doc = CortexDocument()
+    doc.meta = {
+        "path": "<template:brain>",
+        "format": ".cortex",
+        "version": "1.0.0",
+        "hash": "",
+    }
+    doc.glossary = build_minimal_glossary(brain_sigils())
+
+    # $0 section (will be serialised from the glossary at write-time)
+    sec0 = Section(id="$0", title="MINIMAL LOCAL GLOSSARY")
+    doc.sections.append(sec0)
+
+    # $1 IDENTITY
+    sec1 = Section(id="$1", title="IDENTITY")
+    sec1.entries.append(build_entry_from_value(
+        "$1", "IDN", "agent", "attrs",
+        {"name": name, "role": "operator"},
+    ))
+    sec1.entries.append(build_entry_from_value(
+        "$1", "IDN", "human", "attrs",
+        {"name": "human", "role": "architect"},
+    ))
+    sec1.entries.append(build_entry_from_value(
+        "$1", "DOM", "workspace", "attrs",
+        {"area": domain, "protocol": "CODEC-CORTEX", "artifact": "brain.cortex"},
+    ))
+    doc.sections.append(sec1)
+
+    # $2 ACTIVE WORK
+    sec2 = Section(id="$2", title="ACTIVE WORK")
+    sec2.entries.append(build_entry_from_value(
+        "$2", "FCS", "primary", "attrs",
+        {
+            "what": "current focus",
+            "priority": "high",
+            "status": "current",
+            "survive": "min",
+        },
+    ))
+    sec2.entries.append(build_entry_from_value(
+        "$2", "OBJ", "main", "attrs",
+        {
+            "goal": "current objective",
+            "status": "current",
+            "success": "verifiable criterion",
+            "survive": "min",
+        },
+    ))
+    sec2.entries.append(build_entry_from_value(
+        "$2", "WRK", "state", "attrs",
+        {
+            "phase": "active",
+            "current": "work state",
+            "blocked": False,
+            "survive": "work",
+        },
+    ))
+    sec2.entries.append(build_entry_from_value(
+        "$2", "STP", "next", "attrs",
+        {
+            "action": "next action",
+            "reason": "why",
+            "owner": owner,
+            "status": "current",
+            "survive": "min",
+        },
+    ))
+    if with_diagrams:
+        sec2.entries.append(build_entry_from_value(
+            "$2", "DIAG", "flow", "bloque",
+            "@startuml\nA --> B\n@enduml",
+        ))
+    doc.sections.append(sec2)
+
+    # $3 GOVERNANCE
+    sec3 = Section(id="$3", title="GOVERNANCE")
+    sec3.entries.append(build_entry_from_value(
+        "$3", "CNST", "self_contained", "attrs",
+        {
+            "rule": "This brain.cortex carries its own minimal $0 and does not require external glossary to begin safe interpretation.",
+            "severity": "blocking",
+            "survive": "min",
+        },
+    ))
+    doc.sections.append(sec3)
+
+    return doc

cortex/templates/minimal_glossary.py

@@ -0,0 +1,42 @@
+"""Minimal-glossary factory — produces a fully-seeded :class:`Glossary`.
+
+The minimal glossary always includes the canonical expansion types
+(attrs, attrs-pos, cuerpo, bloque, relación) and the canonical
+micro-tokens (Section 4.1.1 of SKILL.md).  Sigils are added by the
+template factories (brain / skill / package / generic).
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from ..core.ast import AttrsPosContract, Glossary, SigilDef, TypeDef, MicroDef
+from ..core.errors import CANONICAL_MICRO
+from ..glossary.contracts import DEFAULT_CONTRACTS
+
+
+def build_minimal_glossary(sigils: List[SigilDef]) -> Glossary:
+    """Build a glossary from a list of sigils + canonical types/micro."""
+
+    g = Glossary()
+    # Canonical expansion types
+    for name, desc in [
+        ("attrs", "key:value pairs"),
+        ("attrs-pos", "positional with explicit contract"),
+        ("cuerpo", "free text body"),
+        ("bloque", "verbatim multiline block"),
+        ("relación", "causal A -> B form"),
+    ]:
+        g.add_type(TypeDef(name=name, description=desc))
+    # Canonical micro-tokens
+    for tok, val in CANONICAL_MICRO.items():
+        g.add_micro(MicroDef(token=tok, value=val))
+    # Sigils provided by the caller
+    for sd in sigils:
+        g.add_sigil(sd)
+    # Default contracts for attrs-pos sigils in the sigil set
+    sigil_names = {sd.sigil for sd in sigils}
+    for sig, fields in DEFAULT_CONTRACTS.items():
+        if sig in sigil_names:
+            g.add_contract(AttrsPosContract(sigil=sig, fields=list(fields)))
+    return g

cortex/templates/package.py

@@ -0,0 +1,91 @@
+"""Nivel 3 ``package.cortex`` template factory.
+
+Builds a transportable context package with:
+  - $0: minimal local glossary
+  - $1: PACKAGE IDENTITY (IDN:package, DOM:scope)
+  - $2: CONTENT (KNW:topic, REF:source)
+  - $3: LIMITS (LIM:package_lifecycle, CLAIM:self_contained)
+
+Mirrors Section 18.3 of SKILL.md.
+"""
+
+from __future__ import annotations
+
+from ..core.ast import CortexDocument, Section
+from ..core.parser import build_entry_from_value
+from ..glossary.minimal import package_sigils
+from .minimal_glossary import build_minimal_glossary
+
+
+def build_package(
+    name: str = "context_package",
+    version: str = "0.1.0",
+    domain: str = "specific domain",
+    owner: str = "source",
+    language: str = "en",
+    template: str = "standard",
+    with_diagrams: bool = False,
+) -> CortexDocument:
+    doc = CortexDocument()
+    doc.meta = {
+        "path": "<template:package>",
+        "format": ".cortex",
+        "version": version,
+        "hash": "",
+    }
+    doc.glossary = build_minimal_glossary(package_sigils())
+
+    sec0 = Section(id="$0", title="MINIMAL LOCAL GLOSSARY")
+    doc.sections.append(sec0)
+
+    sec1 = Section(id="$1", title="PACKAGE IDENTITY")
+    sec1.entries.append(build_entry_from_value(
+        "$1", "IDN", "package", "attrs",
+        {"name": name, "version": version, "status": "current"},
+    ))
+    sec1.entries.append(build_entry_from_value(
+        "$1", "DOM", "scope", "attrs",
+        {"area": domain, "owner": owner, "purpose": "context injection"},
+    ))
+    doc.sections.append(sec1)
+
+    sec2 = Section(id="$2", title="CONTENT")
+    sec2.entries.append(build_entry_from_value(
+        "$2", "KNW", "topic", "attrs",
+        {
+            "topic": "domain concept",
+            "content": "compressed knowledge",
+            "status": "current",
+        },
+    ))
+    sec2.entries.append(build_entry_from_value(
+        "$2", "REF", "source", "attrs",
+        {"PATH": "source.md", "purpose": "traceability"},
+    ))
+    if with_diagrams:
+        sec2.entries.append(build_entry_from_value(
+            "$2", "DIAG", "overview", "bloque",
+            "@startuml\n[A]-->[B]\n@enduml",
+        ))
+    doc.sections.append(sec2)
+
+    sec3 = Section(id="$3", title="LIMITS")
+    sec3.entries.append(build_entry_from_value(
+        "$3", "LIM", "package_lifecycle", "attrs",
+        {
+            "limit": "package does not mature by itself until formally absorbed by Level 2",
+            "scope": "level_3",
+            "status": "current",
+        },
+    ))
+    sec3.entries.append(build_entry_from_value(
+        "$3", "CLAIM", "self_contained", "attrs",
+        {
+            "statement": "This package includes its own minimal $0 for safe initial interpretation.",
+            "evidence": "$0 section present",
+            "status": "current",
+        },
+    ))
+    doc.sections.append(sec3)
+
+    return doc

cortex/templates/skill.py

@@ -0,0 +1,91 @@
+"""``SKILL.cortex`` template factory.
+
+Builds a Nivel 1 (mind) skill document with:
+  - $0: UNIVERSAL GLOSSARY
+  - $1: IDENTITY (IDN:skill, DOM:protocol)
+  - $2: AXIOMS (AXM:level_separation, AXM:self_contained)
+
+Mirrors Section 18.1 of SKILL.md.
+"""
+
+from __future__ import annotations
+
+from ..core.ast import CortexDocument, Section
+from ..core.parser import build_entry_from_value
+from ..glossary.minimal import skill_sigils
+from .minimal_glossary import build_minimal_glossary
+
+
+def build_skill(
+    name: str = "codec-cortex",
+    version: str = "1.0.0",
+    domain: str = "LLM/SLM contextual memory",
+    owner: str = "agent",
+    language: str = "en",
+    template: str = "standard",
+    with_diagrams: bool = False,
+) -> CortexDocument:
+    doc = CortexDocument()
+    doc.meta = {
+        "path": "<template:skill>",
+        "format": ".cortex",
+        "version": version,
+        "hash": "",
+    }
+    doc.glossary = build_minimal_glossary(skill_sigils())
+
+    sec0 = Section(id="$0", title="UNIVERSAL GLOSSARY")
+    doc.sections.append(sec0)
+
+    sec1 = Section(id="$1", title="IDENTITY")
+    sec1.entries.append(build_entry_from_value(
+        "$1", "IDN", "skill", "attrs",
+        {
+            "name": name,
+            "version": version,
+            "status": "specification",
+            "nature": "cognitive_memory_protocol",
+        },
+    ))
+    sec1.entries.append(build_entry_from_value(
+        "$1", "DOM", "protocol", "attrs",
+        {
+            "area": domain,
+            "format": ".cortex",
+            "memory_output": "HCORTEX",
+            "conversational_output": "CORTEX-OUT",
+        },
+    ))
+    doc.sections.append(sec1)
+
+    sec2 = Section(id="$2", title="AXIOMS")
+    sec2.entries.append(build_entry_from_value(
+        "$2", "AXM", "level_separation", "cuerpo",
+        "SKILL.cortex governs behavior and contracts. It never stores live working state.",
+    ))
+    sec2.entries.append(build_entry_from_value(
+        "$2", "AXM", "self_contained", "cuerpo",
+        "Every .cortex artifact must include a minimal $0 local glossary for safe interpretation.",
+    ))
+    doc.sections.append(sec2)
+
+    sec3 = Section(id="$3", title="CONSTRAINTS")
+    sec3.entries.append(build_entry_from_value(
+        "$3", "CNST", "no_live_state_in_skill", "attrs",
+        {
+            "rule": "SKILL.cortex MUST NOT contain FCS/OBJ/WRK/STP/NXT as live state.",
+            "severity": "blocking",
+            "survive": "min",
+        },
+    ))
+    doc.sections.append(sec3)
+
+    if with_diagrams:
+        sec6 = Section(id="$6", title="DIAGRAMS")
+        sec6.entries.append(build_entry_from_value(
+            "$6", "DIAG", "architecture", "bloque",
+            "@startuml\n[A]-->[B]\n@enduml",
+        ))
+        doc.sections.append(sec6)
+
+    return doc

cortex/v2/__init__.py

@@ -0,0 +1,30 @@
+r"""CODEC-CORTEX v2 — High-fidelity CORTEX <-> HCORTEX translation.
+
+v2.2.1: HCORTEX is reversible by definition when VIEW coverage is valid.
+HCORTEX-R eliminated as separate concept.
+"""
+
+from .parser import parse_cortex_v2, CortexV2Document
+from .writer import write_cortex_v2
+from .ir import SkillIR, IREntry, IRBlock, IRWarning, cortex_to_ir, ir_to_cortex
+from .hcortex_renderer import render_hcortex_v2
+from .view import (
+    ViewDirective, ViewKind, ReverseStrategy, ViewDiagnostic,
+    parse_view_entry, parse_view_entries_from_doc,
+    resolve_target, calculate_view_coverage,
+    VALID_KINDS, VALID_REVERSES, KIND_REVERSE_COMPAT,
+)
+from .view_renderer import render_hcortex, render_hcortex_r, has_view_errors
+
+__all__ = [
+    "parse_cortex_v2", "write_cortex_v2", "CortexV2Document",
+    "SkillIR", "IREntry", "IRBlock", "IRWarning",
+    "cortex_to_ir", "ir_to_cortex",
+    "render_hcortex_v2",
+    # VIEW
+    "ViewDirective", "ViewKind", "ReverseStrategy", "ViewDiagnostic",
+    "parse_view_entry", "parse_view_entries_from_doc",
+    "resolve_target", "calculate_view_coverage",
+    "VALID_KINDS", "VALID_REVERSES", "KIND_REVERSE_COMPAT",
+    "render_hcortex", "render_hcortex_r", "has_view_errors",
+]

cortex/v2/diagnostics.py

@@ -0,0 +1,57 @@
+"""Diagnostics for v2.3.0 — formal error taxonomy.
+
+11 error codes + 1 warning per spec section 5.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Diagnostic dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Diagnostic:
+    code: str
+    message: str
+    severity: str = "error"  # error | warning | info
+    location: Optional[str] = None  # e.g. "VIEW:foo", "$0/IDN:project"
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "severity": self.severity,
+            "location": self.location,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Formal error codes (v2.3.0 spec section 5)
+# ---------------------------------------------------------------------------
+
+ERROR_CODES = {
+    # HCORTEX-level
+    "E_HCORTEX_HEADER_INVALID":      "Header ausente o inválido",
+    "E_HCORTEX_NOT_REVERSIBLE":      "Declara o requiere reversión pero no cumple",
+    "E_VIEW_MISSING":                "Bloque semántico sin VIEW",
+    "E_VIEW_TARGET_UNRESOLVED":      "Target no resoluble",
+    "E_VIEW_REVERSE_UNSUPPORTED":    "Estrategia inversa no soportada",
+    "E_VIEW_HASH_MISMATCH":          "Hash no coincide",
+    "E_HUMAN_BLOCK_UNDECLARED":      "Prosa humana no marcada",
+    "E_TABLE_SCHEMA_MISMATCH":       "Tabla no coincide con fields declarados",
+    "E_BLOCK_NOT_PRESERVED":         "Bloque verbatim alterado",
+    "E_AST_EQUIVALENCE_FAIL":        "No se conserva equivalencia AST",
+    "W_HCORTEX_DISPLAY_ONLY":        "Markdown legible, pero no HCORTEX canónico",
+}
+
+
+def has_errors(diags: List[Diagnostic]) -> bool:
+    return any(d.severity == "error" for d in diags)
+
+
+def has_view_errors(diags: List[Diagnostic]) -> bool:
+    return any(d.code.startswith("E_VIEW_") and d.severity == "error" for d in diags)