devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/templates/library/engine.py

@@ -0,0 +1,228 @@
+"""Reasoning template library for DevTorch.
+
+Provides built-in reasoning templates and a documented extension API for
+project-level custom templates under ``.devtorch/templates/`` or ``templates/``.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "list_builtin_templates",
+    "load_builtin_template",
+    "discover_custom_templates",
+    "apply_template",
+    "render_template",
+]
+
+_BUILTIN_DIR = Path(__file__).resolve().parent
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}")
+
+
+def _parse_front_matter(text: str) -> tuple[dict[str, Any], str]:
+    """Parse a minimal YAML-like front-matter block at the top of ``text``.
+
+    Returns a ``(metadata, body)`` tuple.  Only the scalar keys required by
+    the library (``name``, ``description``, ``tags``) are parsed, and ``tags``
+    is normalised to a list of strings.
+    """
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+
+    end = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+
+    if end == -1:
+        return {}, text
+
+    meta_text = "\n".join(lines[1:end])
+    body = "\n".join(lines[end + 1 :])
+    metadata: dict[str, Any] = {}
+
+    for line in meta_text.splitlines():
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            continue
+
+        # Strip matching quotes.
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+            value = value[1:-1]
+
+        if key == "tags":
+            value = _parse_tags(value)
+
+        metadata[key] = value
+
+    return metadata, body
+
+
+def _parse_tags(value: str) -> list[str]:
+    """Parse ``tags`` as a YAML list ``[a, b]`` or a comma-separated string."""
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [
+            item.strip().strip('"\'')
+            for item in inner.split(",")
+            if item.strip()
+        ]
+    if value:
+        return [item.strip() for item in value.split(",") if item.strip()]
+    return []
+
+
+def list_builtin_templates() -> list[dict[str, Any]]:
+    """Return metadata for every built-in reasoning template.
+
+    Each entry contains at least ``name``, ``description``, ``tags``, and
+    ``filename``.
+    """
+    templates: list[dict[str, Any]] = []
+    if not _BUILTIN_DIR.exists():
+        return templates
+
+    for path in sorted(_BUILTIN_DIR.glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        meta, _ = _parse_front_matter(text)
+        templates.append(
+            {
+                "name": meta.get("name", path.stem),
+                "description": meta.get("description", ""),
+                "tags": meta.get("tags", []),
+                "filename": path.name,
+            }
+        )
+
+    return templates
+
+
+def load_builtin_template(name: str) -> str:
+    """Return the raw Markdown text of a built-in template.
+
+    Raises:
+        ValueError: if the template is not built-in.
+    """
+    path = _BUILTIN_DIR / f"{name}.md"
+    if not path.exists():
+        raise ValueError(f"Unknown built-in template: {name}")
+    return path.read_text(encoding="utf-8")
+
+
+def discover_custom_templates(project_root: Path | str) -> list[dict[str, Any]]:
+    """Discover custom templates under ``.devtorch/templates/`` and ``templates/``.
+
+    Templates are returned in discovery order: ``.devtorch/templates/`` first,
+    then project-level ``templates/``.
+    """
+    root = Path(project_root).resolve()
+    origins = [root / ".devtorch" / "templates", root / "templates"]
+    templates: list[dict[str, Any]] = []
+
+    for origin_dir in origins:
+        if not origin_dir.is_dir():
+            continue
+        for path in sorted(origin_dir.glob("*.md")):
+            text = path.read_text(encoding="utf-8")
+            meta, _ = _parse_front_matter(text)
+            try:
+                origin = str(path.parent.relative_to(root))
+            except ValueError:
+                origin = str(path.parent)
+            templates.append(
+                {
+                    "name": meta.get("name", path.stem),
+                    "description": meta.get("description", ""),
+                    "tags": meta.get("tags", []),
+                    "path": str(path),
+                    "origin": origin,
+                }
+            )
+
+    return templates
+
+
+def render_template(template_text: str, variables: dict[str, Any]) -> str:
+    """Replace ``{{variable}}`` placeholders with values from ``variables``.
+
+    Unknown placeholders are left untouched so callers can see what is still
+    required.
+    """
+    string_vars = {str(k): str(v) for k, v in variables.items()}
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return string_vars.get(key, match.group(0))
+
+    return _PLACEHOLDER_RE.sub(_replace, template_text)
+
+
+def _resolve_template(name: str, project_root: Path | str | None = None) -> str:
+    """Load template text from built-ins or, optionally, custom directories.
+
+    Custom templates take precedence over built-ins when a name collision
+    occurs, so projects can extend or override the default reasoning library.
+    """
+    if project_root is not None:
+        for custom in discover_custom_templates(project_root):
+            if custom["name"] == name:
+                return Path(custom["path"]).read_text(encoding="utf-8")
+
+    builtin_path = _BUILTIN_DIR / f"{name}.md"
+    if builtin_path.exists():
+        return builtin_path.read_text(encoding="utf-8")
+
+    raise ValueError(f"Unknown template: {name}")
+
+
+def _default_output_path(name: str, project_root: Path | str | None = None) -> Path:
+    """Default render target inside ``.GCC/templates/rendered/``."""
+    root = Path(project_root) if project_root else Path.cwd()
+    return root / ".GCC" / "templates" / "rendered" / f"{name}.md"
+
+
+def apply_template(
+    name: str,
+    variables: dict[str, Any],
+    output_path: Path | str | None = None,
+    project_root: Path | str | None = None,
+) -> Path:
+    """Render a template (built-in or custom) and write it to ``output_path``.
+
+    If ``output_path`` is not provided, the rendered output is written to
+    ``.GCC/templates/rendered/<name>.md`` relative to ``project_root`` (or the
+    current working directory if ``project_root`` is not given).
+
+    Args:
+        name: Template name (matches the filename stem, or the ``name`` field
+            in the front matter).
+        variables: Mapping of placeholder names to values.
+        output_path: Destination path for the rendered template.
+        project_root: Optional project root used to resolve custom templates
+            and default output paths.
+
+    Returns:
+        The absolute path where the rendered template was written.
+
+    Raises:
+        ValueError: if the template cannot be found.
+    """
+    template_text = _resolve_template(name, project_root)
+    rendered = render_template(template_text, variables)
+
+    out = Path(output_path) if output_path else _default_output_path(name, project_root)
+    out = out.resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(rendered, encoding="utf-8")
+    return out

devtorch_core/templates/library/security_review.md

@@ -0,0 +1,30 @@
+---
+name: security_review
+description: Structured reasoning for a security review or threat assessment
+tags: [reasoning, security, review]
+---
+# Security Review: {{title}}
+
+## Scope
+{{scope}}
+
+## Threat model
+{{threat_model}}
+
+## Controls evaluated
+{{controls}}
+
+## Findings
+{{findings}}
+
+## Risk assessment
+{{reasoning}}
+
+## Remediation
+{{remediation}}
+
+## Verification
+{{verification}}
+
+## Disclosure level
+{{disclosure_level}}

devtorch_core/templates/python.py

@@ -0,0 +1,19 @@
+"""Built-in Python project template."""
+from __future__ import annotations
+
+from devtorch_core.templates.engine import Template
+
+TEMPLATE = Template(
+    name="python",
+    display_name="Python",
+    project_type="python",
+    concepts=[
+        ("auth", "Authentication, authorization, and identity management."),
+        ("schema", "Data models, validation schemas, and serialization."),
+        ("api", "Public interfaces, endpoints, and service contracts."),
+        ("data", "Persistence, queries, and data lifecycle."),
+        ("cli", "Command-line interface and entry points."),
+        ("tests", "Automated tests, fixtures, and coverage."),
+    ],
+    governance_note="Python projects default to explicit schemas, tested APIs, and clear separation between CLI, business logic, and data layers.",
+)

devtorch_core/templates/react.py

@@ -0,0 +1,18 @@
+"""Built-in React project template."""
+from __future__ import annotations
+
+from devtorch_core.templates.engine import Template
+
+TEMPLATE = Template(
+    name="react",
+    display_name="React",
+    project_type="react",
+    concepts=[
+        ("auth", "Authentication, authorization, and session handling."),
+        ("schema", "Prop types, data shapes, and API response schemas."),
+        ("api", "Backend integration, hooks, and service clients."),
+        ("ui", "Screens, layouts, and user interaction design."),
+        ("components", "Reusable components, composition, and state ownership."),
+    ],
+    governance_note="React projects default to component-driven UI, explicit data schemas, and isolated auth/session concerns separated from presentation logic.",
+)

devtorch_core/templates/typescript.py

@@ -0,0 +1,18 @@
+"""Built-in TypeScript project template."""
+from __future__ import annotations
+
+from devtorch_core.templates.engine import Template
+
+TEMPLATE = Template(
+    name="typescript",
+    display_name="TypeScript",
+    project_type="typescript",
+    concepts=[
+        ("auth", "Authentication, authorization, and identity management."),
+        ("schema", "Type definitions, validation schemas, and runtime checks."),
+        ("api", "HTTP, RPC, and library interfaces."),
+        ("ui", "User-facing components and interaction patterns."),
+        ("types", "Shared type definitions and generic contracts."),
+    ],
+    governance_note="TypeScript projects default to strict type contracts, schema-first APIs, and shared type definitions across UI and service boundaries.",
+)

devtorch_core/theta.py

@@ -0,0 +1,221 @@
+"""
+Sprint 3 – Coordination vector Θ and pluggable Aggφ aggregation.
+
+ThetaStore persists Θ (a concept → summary mapping) at `.GCC/theta.json`.
+AggPhi is an abstract interface; RulesBasedAggPhi is the default implementation
+that averages confidence with recency weighting and escalates disclosure levels.
+
+Callers invoke `ThetaStore.ripple(events)` to merge a batch of sensitivity
+event dicts into the stored Θ, using the configured AggPhi.
+"""
+
+from __future__ import annotations
+
+import abc
+import datetime as _dt
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+THETA_FILE = "theta.json"
+
+# Ordered disclosure level ranks (higher index = more restrictive)
+_LEVEL_RANK: Dict[str, int] = {"PUBLIC": 0, "PROTECTED": 1, "PRIVATE": 2}
+_RANK_LEVEL: Dict[int, str] = {0: "PUBLIC", 1: "PROTECTED", 2: "PRIVATE"}
+
+
+class AggPhi(abc.ABC):
+    """
+    Pluggable aggregation interface (Aggφ).
+
+    Implementations receive a list of raw sensitivity event dicts and return a
+    *partial theta delta*: a mapping of concept → aggregated entry containing
+    at minimum:
+        mean_confidence  : float
+        disclosure_level : str  ("PUBLIC" | "PROTECTED" | "PRIVATE")
+        event_count      : int
+    """
+
+    @abc.abstractmethod
+    def aggregate(self, events: List[dict]) -> Dict[str, dict]:
+        """Aggregate *events* into a per-concept summary delta."""
+
+
+class RulesBasedAggPhi(AggPhi):
+    """
+    Default rules-based Aggφ.
+
+    Aggregation rules:
+    1. Group events by `target_concept`.
+    2. Within each group, sort by `created_at` descending (newest first).
+    3. Apply recency weighting: the newest event has weight 2.0; all others 1.0.
+    4. Compute weighted mean confidence.
+    5. Escalate disclosure level to the maximum seen in the group.
+    """
+
+    def aggregate(self, events: List[dict]) -> Dict[str, dict]:
+        grouped: Dict[str, List[dict]] = {}
+        for ev in events:
+            concept = ev.get("target_concept", "unknown")
+            grouped.setdefault(concept, []).append(ev)
+
+        result: Dict[str, dict] = {}
+        for concept, group in grouped.items():
+            sorted_group = sorted(
+                group,
+                key=lambda e: e.get("created_at", ""),
+                reverse=True,
+            )
+            total_weight = 0.0
+            weighted_conf = 0.0
+            max_rank = 0
+
+            for i, ev in enumerate(sorted_group):
+                weight = 2.0 if i == 0 else 1.0
+                conf = float(ev.get("confidence", 0.5))
+                weighted_conf += weight * conf
+                total_weight += weight
+
+                rank = _LEVEL_RANK.get(ev.get("disclosure_level", "PUBLIC"), 0)
+                if rank > max_rank:
+                    max_rank = rank
+
+            mean_conf = weighted_conf / total_weight if total_weight else 0.0
+            result[concept] = {
+                "mean_confidence": round(mean_conf, 6),
+                "disclosure_level": _RANK_LEVEL[max_rank],
+                "event_count": len(group),
+            }
+        return result
+
+
+class ThetaStore:
+    """
+    Persistence layer for the coordination vector Θ.
+
+    The on-disk format is a single JSON object at `.GCC/theta.json`:
+    {
+      "version": 1,
+      "updated_at": "<ISO UTC>",
+      "coordination_vector": {
+        "<concept>": {
+          "mean_confidence": 0.85,
+          "disclosure_level": "PROTECTED",
+          "event_count": 5,
+          "last_updated": "<ISO UTC>"
+        }
+      }
+    }
+    """
+
+    def __init__(self, gcc_dir: Path, aggregator: Optional[AggPhi] = None) -> None:
+        self.gcc_dir = gcc_dir
+        self.theta_path = gcc_dir / THETA_FILE
+        self.aggregator: AggPhi = aggregator if aggregator is not None else RulesBasedAggPhi()
+
+    # ------------------------------------------------------------------
+    # Load / save
+    # ------------------------------------------------------------------
+
+    def load(self) -> dict:
+        """Load the current Θ from disk; return a fresh structure if absent."""
+        if not self.theta_path.exists():
+            return {"version": 1, "updated_at": None, "coordination_vector": {}}
+        try:
+            return json.loads(self.theta_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {"version": 1, "updated_at": None, "coordination_vector": {}}
+
+    def save(self, theta: dict) -> None:
+        self.gcc_dir.mkdir(parents=True, exist_ok=True)
+        self.theta_path.write_text(
+            json.dumps(theta, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    # ------------------------------------------------------------------
+    # Ripple propagation
+    # ------------------------------------------------------------------
+
+    def ripple(self, events: List[dict]) -> dict:
+        """
+        Aggregate *events* via Aggφ and merge the delta into the stored Θ.
+
+        Merge rules per concept:
+        - confidence: weighted blend of existing + new (weighted by event counts).
+        - disclosure_level: escalate to the maximum of existing and incoming.
+        - event_count: cumulative sum.
+
+        Returns the updated Θ dict.
+        """
+        delta = self.aggregator.aggregate(events)
+        theta = self.load()
+        cv: dict = theta.setdefault("coordination_vector", {})
+        now = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+
+        for concept, entry in delta.items():
+            existing = cv.get(concept, {})
+            old_count = int(existing.get("event_count", 0))
+            new_count = int(entry["event_count"])
+            total = old_count + new_count
+
+            if total:
+                old_conf = float(existing.get("mean_confidence", entry["mean_confidence"]))
+                new_conf = float(entry["mean_confidence"])
+                blended = (old_conf * old_count + new_conf * new_count) / total
+            else:
+                blended = float(entry["mean_confidence"])
+
+            existing_rank = _LEVEL_RANK.get(existing.get("disclosure_level", "PUBLIC"), 0)
+            new_rank = _LEVEL_RANK.get(entry["disclosure_level"], 0)
+            merged_level = _RANK_LEVEL[max(existing_rank, new_rank)]
+
+            cv[concept] = {
+                "mean_confidence": round(blended, 6),
+                "disclosure_level": merged_level,
+                "event_count": total,
+                "last_updated": now,
+            }
+
+        theta["updated_at"] = now
+        self.save(theta)
+
+        # S8: near-duplicate concept pairs for I3 handshake (Textual Mode Aggφ only)
+        if getattr(self.aggregator, "records_i3_merge_candidates", False):
+            try:
+                from .aggphi_textual import merge_i3_records, near_duplicate_pairs
+
+                thr = float(getattr(self.aggregator, "similarity_threshold", 0.82))
+                theta = self.load()
+                cv_keys = list(theta.setdefault("coordination_vector", {}).keys())
+                pairs = near_duplicate_pairs(cv_keys, threshold=thr)
+                if pairs:
+                    prev = theta.get("pending_i3_merges")
+                    if not isinstance(prev, list):
+                        prev = []
+                    theta["pending_i3_merges"] = merge_i3_records(prev, pairs)
+                    self.save(theta)
+            except Exception:
+                pass
+
+        return self.load()
+
+
+def make_theta_store(gcc_dir: Path) -> ThetaStore:
+    """
+    Construct a :class:`ThetaStore` for *gcc_dir*, respecting ``DEVTORCH_AGGPHI``:
+
+    - ``rules`` (default): :class:`RulesBasedAggPhi`
+    - ``textual`` / ``s8`` / ``text``: :class:`TextualModeAggPhi` (Sprint 8)
+    """
+    mode = os.environ.get("DEVTORCH_AGGPHI", "rules").strip().lower()
+    if mode in ("textual", "s8", "text"):
+        try:
+            from .aggphi_textual import TextualModeAggPhi
+
+            return ThetaStore(gcc_dir, aggregator=TextualModeAggPhi())
+        except Exception:
+            return ThetaStore(gcc_dir)
+    return ThetaStore(gcc_dir)