grain-kit 0.1.0__py3-none-any.whl

grain/adapters/adapter_config.py

@@ -0,0 +1,207 @@
+"""Load and parse adapter profile configuration from runtime markdown."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from grain.adapters.capabilities import GraphAwareAdapterCapability
+from grain.domain.adapters import AdapterProfile
+from grain.domain.errors import ConfigError, MissingPathError
+
+ADAPTER_PROFILES_PATH = "docs/runtime/adapter_profiles.md"
+_PROFILE_SECTION_HEADER = "## 5. Adapter Profiles"
+_PROFILE_HEADER = re.compile(r"^###\s+([a-zA-Z0-9_]+)\s*$")
+_INLINE_FIELD = re.compile(r"^- `([^`]+)`: `([^`]+)`\s*$")
+_LIST_FIELD_HEADER = re.compile(r"^- `([^`]+)`:\s*$")
+
+_REQUIRED_FIELDS: tuple[str, ...] = ("adapter_id", "domain_type", "applies_to")
+_REQUIRED_HINT_FIELDS: tuple[str, ...] = (
+    "context_priority_rules",
+    "test_or_validation_hints",
+)
+
+
+def load_adapter_profiles(root: Path) -> list[AdapterProfile]:
+    """Load adapter profiles from docs/runtime/adapter_profiles.md."""
+    config_path = root / ADAPTER_PROFILES_PATH
+    if not config_path.exists():
+        raise MissingPathError(
+            f"Adapter profile config not found: {ADAPTER_PROFILES_PATH}",
+            detail=str(config_path),
+        )
+
+    text = config_path.read_text(encoding="utf-8")
+    profiles = parse_adapter_profiles_markdown(text)
+    for profile in profiles:
+        profile.capabilities = GraphAwareAdapterCapability(root, profile)
+    return profiles
+
+
+def parse_adapter_profiles_markdown(text: str) -> list[AdapterProfile]:
+    """Parse adapter profiles from adapter_profiles runtime markdown."""
+    lines = text.splitlines()
+    profile_start = _find_profile_section(lines)
+    if profile_start is None:
+        raise ConfigError(
+            "Adapter profile config is incomplete",
+            detail="Missing '## 5. Adapter Profiles' section",
+        )
+
+    profiles: list[AdapterProfile] = []
+    index = profile_start + 1
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if stripped.startswith("## "):
+            break
+
+        profile_match = _PROFILE_HEADER.match(stripped)
+        if not profile_match:
+            index += 1
+            continue
+
+        section_name = profile_match.group(1)
+        fields, index = _parse_profile_fields(lines, index + 1)
+        profiles.append(_build_profile(section_name, fields))
+
+    if not profiles:
+        raise ConfigError(
+            "Adapter profile config is incomplete",
+            detail="No adapter profiles found in '## 5. Adapter Profiles' section",
+        )
+
+    return profiles
+
+
+def _find_profile_section(lines: list[str]) -> int | None:
+    """Return line index for adapter profile section header."""
+    for index, line in enumerate(lines):
+        if line.strip() == _PROFILE_SECTION_HEADER:
+            return index
+    return None
+
+
+def _parse_profile_fields(
+    lines: list[str],
+    start_index: int,
+) -> tuple[dict[str, object], int]:
+    """Parse one adapter profile field block under a ### profile header."""
+    fields: dict[str, object] = {}
+    index = start_index
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if _PROFILE_HEADER.match(stripped) or stripped.startswith("## "):
+            break
+
+        inline_match = _INLINE_FIELD.match(stripped)
+        if inline_match:
+            fields[inline_match.group(1)] = inline_match.group(2).strip()
+            index += 1
+            continue
+
+        list_header_match = _LIST_FIELD_HEADER.match(stripped)
+        if list_header_match:
+            items, index = _consume_bullets(lines, index + 1)
+            fields[list_header_match.group(1)] = items
+            continue
+
+        index += 1
+
+    return fields, index
+
+
+def _consume_bullets(lines: list[str], start_index: int) -> tuple[list[str], int]:
+    """Collect contiguous markdown bullet items starting at start_index."""
+    items: list[str] = []
+    index = start_index
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if not stripped:
+            index += 1
+            continue
+        if _INLINE_FIELD.match(stripped) or _LIST_FIELD_HEADER.match(stripped):
+            break
+        if stripped.startswith("- "):
+            items.append(_strip_backticks(stripped[2:].strip()))
+            index += 1
+            continue
+        break
+    return items, index
+
+
+def _build_profile(section_name: str, fields: dict[str, object]) -> AdapterProfile:
+    """Validate parsed fields and convert them into an AdapterProfile."""
+    missing_fields = [name for name in _REQUIRED_FIELDS if not fields.get(name)]
+    if missing_fields:
+        missing = ", ".join(missing_fields)
+        raise ConfigError(
+            "Adapter profile config is incomplete",
+            detail=f"Missing required field(s) in '{section_name}': {missing}",
+        )
+
+    adapter_id = _as_text(fields.get("adapter_id"))
+    if adapter_id != section_name:
+        raise ConfigError(
+            "Adapter profile config is invalid",
+            detail=(
+                f"Section '{section_name}' has adapter_id '{adapter_id}'. "
+                "Header and adapter_id must match."
+            ),
+        )
+
+    domain_type = _as_text(fields.get("domain_type"))
+    applies_to = _as_list(fields.get("applies_to"))
+    if not applies_to:
+        raise ConfigError(
+            "Adapter profile config is incomplete",
+            detail=f"Field 'applies_to' must include at least one item in '{section_name}'",
+        )
+
+    hint_presence = any(_as_list(fields.get(name)) for name in _REQUIRED_HINT_FIELDS)
+    if not hint_presence:
+        required = ", ".join(_REQUIRED_HINT_FIELDS)
+        raise ConfigError(
+            "Adapter profile config is incomplete",
+            detail=(
+                f"Adapter '{section_name}' must include at least one hint section: {required}"
+            ),
+        )
+
+    return AdapterProfile(
+        adapter_id=adapter_id,
+        domain_type=domain_type,
+        applies_to=applies_to,
+        relevant_file_patterns=_as_list(fields.get("relevant_file_patterns")),
+        ignore_file_patterns=_as_list(fields.get("ignore_file_patterns")),
+        build_or_run_hints=_as_list(fields.get("build_or_run_hints")),
+        test_or_validation_hints=_as_list(fields.get("test_or_validation_hints")),
+        review_focus_hints=_as_list(fields.get("review_focus_hints")),
+        context_priority_rules=_as_list(fields.get("context_priority_rules")),
+        default_model_bias=_as_list(fields.get("default_model_bias")),
+    )
+
+
+def _as_text(value: object) -> str:
+    """Normalize a parsed scalar field into text."""
+    if value is None:
+        return ""
+    if isinstance(value, list):
+        return value[0] if value else ""
+    return _strip_backticks(str(value).strip())
+
+
+def _as_list(value: object) -> list[str]:
+    """Normalize a parsed field into a list of strings."""
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [_strip_backticks(str(item).strip()) for item in value if str(item).strip()]
+    text = _strip_backticks(str(value).strip())
+    return [text] if text else []
+
+
+def _strip_backticks(value: str) -> str:
+    """Remove one layer of surrounding markdown backticks."""
+    if len(value) >= 2 and value.startswith("`") and value.endswith("`"):
+        return value[1:-1]
+    return value

grain/adapters/capabilities.py

@@ -0,0 +1,199 @@
+"""Adapter capability implementations backed by structural graph outputs."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+from grain.domain.adapters import (
+    AdapterProfile,
+    ArtifactPattern,
+    ContextHint,
+    FollowupSuggestion,
+    ImpactSignal,
+    ScopeSignal,
+    ValidationRequirement,
+)
+from grain.services.graph_service import build_knowledge_graph
+
+_GRAPH_HOPS_FOR_IMPACT = 2
+_CANDIDATE_LIMIT = 80
+
+
+class GraphAwareAdapterCapability:
+    """Adapter capability implementation using graph outputs when available.
+
+    Falls back to deterministic static profile signals when graph construction
+    does not provide useful data.
+    """
+
+    def __init__(self, root: Path, profile: AdapterProfile):
+        self.root = root
+        self.profile = profile
+
+    def detect_scope(self, scope_description: str) -> ScopeSignal:
+        candidates = _candidate_files(self.root, self.profile)
+        if not candidates:
+            return _static_scope_signal(self.profile)
+
+        result, artifact = build_knowledge_graph(
+            self.root,
+            candidates,
+            produced_by=f"adapter_capability.detect_scope.{self.profile.adapter_id}",
+        )
+        if not result.ok or artifact is None:
+            return _static_scope_signal(self.profile)
+
+        file_paths = _graph_file_paths(artifact)
+        if not file_paths:
+            return _static_scope_signal(self.profile)
+
+        relevant_areas = sorted(
+            {self.profile.domain_type, *self.profile.applies_to, *[node.kind for node in artifact.nodes]}
+        )
+        return ScopeSignal(
+            file_patterns=file_paths,
+            relevant_areas=relevant_areas,
+        )
+
+    def collect_context(self, task_description: str) -> ContextHint:
+        return ContextHint(
+            file_patterns=self.profile.relevant_file_patterns,
+            priority_rules=self.profile.context_priority_rules,
+        )
+
+    def analyze_impact(self, touched_files: list[str]) -> ImpactSignal:
+        candidates = _candidate_files(self.root, self.profile)
+        graph_sources = _dedupe_preserve_order([*touched_files, *candidates])
+        if not graph_sources:
+            return ImpactSignal(affected_files=[], downstream_areas=[self.profile.domain_type])
+
+        result, artifact = build_knowledge_graph(
+            self.root,
+            graph_sources,
+            produced_by=f"adapter_capability.analyze_impact.{self.profile.adapter_id}",
+        )
+        if not result.ok or artifact is None:
+            return ImpactSignal(
+                affected_files=_dedupe_preserve_order(touched_files),
+                downstream_areas=[self.profile.domain_type],
+            )
+
+        adjacency = _graph_adjacency(artifact)
+        file_node_to_path = {
+            node.id: str(node.metadata.get("path", ""))
+            for node in artifact.nodes
+            if node.kind in {"file", "canonical_doc", "runtime_doc"}
+            and isinstance(node.metadata.get("path", ""), str)
+            and str(node.metadata.get("path", ""))
+        }
+        start_nodes = [
+            f"file::{path}"
+            for path in touched_files
+            if f"file::{path}" in file_node_to_path
+        ]
+        if not start_nodes:
+            return ImpactSignal(
+                affected_files=_dedupe_preserve_order(touched_files),
+                downstream_areas=[self.profile.domain_type],
+            )
+
+        impacted_nodes = _reachable_within_hops(adjacency, start_nodes, _GRAPH_HOPS_FOR_IMPACT)
+        impacted_paths = _dedupe_preserve_order(
+            [file_node_to_path[node_id] for node_id in impacted_nodes if node_id in file_node_to_path]
+        )
+        downstream_areas = sorted(
+            {self.profile.domain_type, *[node.kind for node in artifact.nodes if node.id in impacted_nodes]}
+        )
+        return ImpactSignal(
+            affected_files=impacted_paths,
+            downstream_areas=downstream_areas,
+        )
+
+    def validate_changes(self, task_description: str) -> ValidationRequirement:
+        return ValidationRequirement(requirements=self.profile.test_or_validation_hints)
+
+    def export_artifacts(self, task_description: str) -> ArtifactPattern:
+        patterns = [f"adapter:{self.profile.adapter_id}", *self.profile.relevant_file_patterns]
+        return ArtifactPattern(patterns=_dedupe_preserve_order(patterns))
+
+    def suggest_followups(self, execution_outcome: str) -> FollowupSuggestion:
+        followups = []
+        if self.profile.review_focus_hints:
+            followups.append(f"review-focus:{self.profile.review_focus_hints[0]}")
+        if self.profile.test_or_validation_hints:
+            followups.append(f"validate:{self.profile.test_or_validation_hints[0]}")
+        return FollowupSuggestion(followups=followups)
+
+
+def _candidate_files(root: Path, profile: AdapterProfile) -> list[str]:
+    if not profile.relevant_file_patterns:
+        return []
+    candidates: list[str] = []
+    for pattern in profile.relevant_file_patterns:
+        for matched in root.glob(pattern):
+            if not matched.is_file():
+                continue
+            rel = matched.relative_to(root).as_posix()
+            if any(fnmatch.fnmatch(rel, pat) for pat in profile.ignore_file_patterns):
+                continue
+            candidates.append(rel)
+    return _dedupe_preserve_order(candidates)[:_CANDIDATE_LIMIT]
+
+
+def _static_scope_signal(profile: AdapterProfile) -> ScopeSignal:
+    return ScopeSignal(
+        file_patterns=profile.relevant_file_patterns,
+        relevant_areas=sorted({profile.domain_type, *profile.applies_to}),
+    )
+
+
+def _graph_file_paths(artifact) -> list[str]:
+    paths: list[str] = []
+    for node in artifact.nodes:
+        if node.kind not in {"file", "canonical_doc", "runtime_doc"}:
+            continue
+        path = node.metadata.get("path", "")
+        if isinstance(path, str) and path:
+            paths.append(path)
+    return _dedupe_preserve_order(paths)
+
+
+def _graph_adjacency(artifact) -> dict[str, set[str]]:
+    adjacency: dict[str, set[str]] = {}
+    for edge in artifact.edges:
+        adjacency.setdefault(edge.source, set()).add(edge.target)
+        adjacency.setdefault(edge.target, set()).add(edge.source)
+    return adjacency
+
+
+def _reachable_within_hops(
+    adjacency: dict[str, set[str]],
+    start_nodes: list[str],
+    max_hops: int,
+) -> set[str]:
+    seen: set[str] = set(start_nodes)
+    frontier: set[str] = set(start_nodes)
+    for _ in range(max_hops):
+        next_frontier: set[str] = set()
+        for node in frontier:
+            for neighbor in adjacency.get(node, set()):
+                if neighbor in seen:
+                    continue
+                seen.add(neighbor)
+                next_frontier.add(neighbor)
+        if not next_frontier:
+            break
+        frontier = next_frontier
+    return seen
+
+
+def _dedupe_preserve_order(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        if item in seen:
+            continue
+        seen.add(item)
+        out.append(item)
+    return out

grain/adapters/export.py

@@ -0,0 +1,104 @@
+"""Export adapter for context bundle outputs."""
+
+from pathlib import Path
+
+from grain.domain.context import ContextBundle
+from grain.services.docs_extractor import DocsExtractor
+from grain.services.pdf_extractor import PdfExtractor
+from grain.services.spreadsheet_extractor import SpreadsheetExtractor
+
+
+def render_context_markdown_export(root: Path, bundle: ContextBundle) -> str:
+    """Render a single assembled markdown export for a ContextBundle."""
+    generated_at = bundle.export_metadata.get("generated_at", "")
+    sources = bundle.export_metadata.get("sources", [])
+    adapter_context = bundle.export_metadata.get("adapter_context", {})
+    primary_adapter = str(adapter_context.get("primary_adapter", "none"))
+    review_hints = adapter_context.get("review_focus_hints", [])
+    validation_hints = adapter_context.get("test_or_validation_hints", [])
+
+    lines: list[str] = [
+        "# Context Export",
+        "",
+        f"Task ID: {bundle.task_id}",
+        f"Generated At: {generated_at}",
+        f"Primary Adapter: {primary_adapter}",
+    ]
+
+    if primary_adapter != "none":
+        lines.extend(
+            [
+                "",
+                "## Adapter Hints",
+                "",
+                "### Review Focus Hints",
+            ]
+        )
+        if review_hints:
+            for hint in review_hints:
+                lines.append(f"- {hint}")
+        else:
+            lines.append("- (none)")
+        lines.extend(["", "### Test/Validation Hints"])
+        if validation_hints:
+            for hint in validation_hints:
+                lines.append(f"- {hint}")
+        else:
+            lines.append("- (none)")
+
+    lines.extend(
+        [
+        "",
+        "## Sources",
+        ]
+    )
+    for source in sources:
+        lines.append(f"- `{source}`")
+
+    for source in sources:
+        source_path = root / source
+        lines.append("")
+        lines.append(f"## Source: `{source}`")
+        if not source_path.exists():
+            lines.append("")
+            lines.append("_Missing source file on disk._")
+            continue
+        lines.append("")
+        lines.append("```md")
+        lines.append(_render_source_content(source_path))
+        lines.append("```")
+
+    return "\n".join(lines).strip() + "\n"
+
+
+def write_context_markdown_export(
+    root: Path,
+    bundle: ContextBundle,
+    output_path: Path | None = None,
+) -> Path:
+    """Write markdown export to disk and return the output path."""
+    if output_path is None:
+        resolved = bundle.packet_dir / "context_export.md"
+    elif output_path.is_absolute():
+        resolved = output_path
+    else:
+        resolved = root / output_path
+
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    content = render_context_markdown_export(root, bundle)
+    resolved.write_text(content, encoding="utf-8")
+    return resolved
+
+
+def _render_source_content(source_path: Path) -> str:
+    suffix = source_path.suffix.lower()
+    if suffix in {".csv", ".xls", ".xlsx"}:
+        return SpreadsheetExtractor().extract(source_path)
+    if suffix == ".docx":
+        return DocsExtractor().extract(source_path)
+    if suffix == ".pdf":
+        return PdfExtractor().extract(source_path)
+    try:
+        return source_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return f"[context_export: binary or non-utf8 source {source_path.name}]"

grain/adapters/filesystem.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+# The presence of this file identifies a valid Forge repository root.
+_REPO_MARKER = "docs/runtime/PROJECT_RULES.md"
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk upward from `start` until the repository root marker is found.
+
+    Raises FileNotFoundError if no marker is found before reaching the filesystem root.
+    """
+    current = start.resolve()
+    while True:
+        if (current / _REPO_MARKER).exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            raise FileNotFoundError(
+                f"Could not find repository root. "
+                f"No '{_REPO_MARKER}' found in '{start}' or any parent directory."
+            )
+        current = parent
+
+
+def resolve_repo_root(repo_option: str | None = None) -> Path:
+    """Return the repository root path.
+
+    Uses `repo_option` directly if provided, otherwise auto-detects from cwd.
+    """
+    if repo_option is not None:
+        return Path(repo_option).resolve()
+    return find_repo_root(Path.cwd())

grain/adapters/manifest.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import yaml
+
+from grain.domain.errors import ConfigError, MissingPathError
+
+MANIFEST_PATH = "docs/runtime/docs_manifest.yaml"
+
+
+def load_manifest(root: Path) -> dict:
+    """Load and parse docs_manifest.yaml from the repository root.
+
+    Args:
+        root: Repository root path.
+
+    Returns:
+        Parsed manifest contents as a dict.
+
+    Raises:
+        MissingPathError: If the manifest file does not exist.
+        ConfigError: If the file exists but contains invalid YAML.
+    """
+    manifest_file = root / MANIFEST_PATH
+    if not manifest_file.exists():
+        raise MissingPathError(
+            f"Manifest not found: {MANIFEST_PATH}",
+            detail=str(manifest_file),
+        )
+    try:
+        with manifest_file.open("r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(
+            f"Manifest is not valid YAML: {MANIFEST_PATH}",
+            detail=str(exc),
+        ) from exc