devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/actors.py

@@ -0,0 +1,481 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from devflow_engine.llm.cli_one_shot import run_one_shot
+
+from .paths import get_idea_paths
+
+
+_REGISTRY_JSON_FILENAME = "users.json"
+_REGISTRY_MD_FILENAME = "users.md"
+
+
+def _load_llm_cli_config() -> tuple[str, str]:
+    base_cmd = os.environ.get("DEVFLOW_LLM_CLI_BASE", "claude --print")
+    delivery = os.environ.get("DEVFLOW_LLM_CLI_DELIVERY", "stdin").strip().lower()
+    if delivery not in {"stdin", "argument"}:
+        raise RuntimeError("DEVFLOW_LLM_CLI_DELIVERY must be stdin or argument")
+    return base_cmd, delivery
+
+
+def _extract_json(text: str) -> str | None:
+    if "```" in text:
+        parts = text.split("```")
+        for i in range(len(parts) - 1):
+            body = parts[i + 1]
+            body_lines = body.splitlines()
+            if body_lines and body_lines[0].strip().lower() in {"json", "javascript"}:
+                body = "\n".join(body_lines[1:])
+            body = body.strip()
+            if body.startswith("{") and body.endswith("}"):
+                return body
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        return text[start:end+1]
+    return None
+
+
+def _call_json_llm(*, repo_root: Path, prompt: dict[str, Any], error_message: str) -> dict[str, Any]:
+    base_cmd, delivery = _load_llm_cli_config()
+    result = run_one_shot(base_cmd=base_cmd, delivery=delivery, prompt=json.dumps(prompt, indent=2, sort_keys=True), cwd=repo_root, timeout_seconds=900)
+    if not result.ok:
+        raise RuntimeError(result.stderr or result.stdout or error_message)
+    raw_json = _extract_json(result.stdout)
+    if raw_json is None:
+        raise RuntimeError(f"Failed to locate JSON in actor normalization output for task={prompt.get('task')!r}.")
+    parsed = json.loads(raw_json)
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"Actor normalization output for task={prompt.get('task')!r} must be a JSON object.")
+    return parsed
+
+
+def _llm_normalize_actor_entries(*, repo_root: Path, idea_actors: list[str], existing_entries: list[dict[str, Any]], sufficient_idea: dict[str, Any]) -> dict[str, Any]:
+    prompt = {
+        "task": "normalize_idea_actors",
+        "instructions": [
+            "Map each raw actor string from the idea into the existing canonical actor registry when possible.",
+            "Use semantic matching, aliases, descriptions, kind, and inheritance.",
+            "If a source actor phrase semantically refers to one or more existing canonical actors, return decision='matched' and canonical_actor_ids.",
+            "A single source actor phrase may legitimately map to multiple canonical actors when it explicitly combines roles like Regular Manager / Super Manager.",
+            "If no existing actor fits, return decision='proposed' with one or more singular canonical proposed actors.",
+            "Never return merged actor labels as canonical outputs. Split combined source phrases into multiple singular canonical actors when appropriate.",
+            "Return JSON only."
+        ],
+        "existing_actors": existing_entries,
+        "idea_actors": idea_actors,
+        "idea_summary": str(sufficient_idea.get("summary") or sufficient_idea.get("description") or ""),
+        "output_schema": {
+            "mappings": [
+                {
+                    "source_actor_text": "string",
+                    "decision": "matched|proposed",
+                    "canonical_actor_ids": ["string"],
+                    "canonical_actor_labels": ["string"],
+                    "proposed_actors": [{"proposed_id": "string", "proposed_label": "string", "kind": "human|system|consumer|null", "inherits_from": "string|null"}],
+                    "rationale": "string"
+                }
+            ]
+        }
+    }
+    return _call_json_llm(repo_root=repo_root, prompt=prompt, error_message="actor normalization LLM command failed")
+
+
+def actor_registry_json_path(repo_root: Path) -> Path:
+    return repo_root / _REGISTRY_JSON_FILENAME
+
+
+def actor_registry_markdown_path(repo_root: Path) -> Path:
+    return repo_root / _REGISTRY_MD_FILENAME
+
+
+def actor_registry_path(repo_root: Path) -> Path:
+    json_path = actor_registry_json_path(repo_root)
+    if json_path.exists():
+        return json_path
+    return actor_registry_markdown_path(repo_root)
+
+
+def normalize_actor_label(value: str) -> str:
+    lowered = value.strip().lower()
+    lowered = re.sub(r"[^a-z0-9]+", " ", lowered)
+    lowered = re.sub(r"\s+", " ", lowered).strip()
+    return lowered
+
+
+def validate_canonical_actor_label(label: str) -> None:
+    text = str(label).strip()
+    if not text:
+        raise RuntimeError("Canonical actor labels must not be empty.")
+    if "/" in text:
+        raise RuntimeError(
+            f"Canonical actor label {text!r} is invalid: use one actor class only and never slash-separated aliases."
+        )
+    lowered = text.lower()
+    if " and/or " in lowered:
+        raise RuntimeError(
+            f"Canonical actor label {text!r} is invalid: do not use merged actor aliases like and/or."
+        )
+    if re.search(r"\bor\b", lowered):
+        raise RuntimeError(
+            f"Canonical actor label {text!r} is invalid: use exactly one primary actor and do not merge actors with 'or'."
+        )
+
+
+def _coerce_actor_list(value: object) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, list):
+        out: list[str] = []
+        for item in value:
+            text = str(item).strip()
+            if text:
+                out.append(text)
+        return out
+    return []
+
+
+def _contains_any(text: str, terms: set[str]) -> bool:
+    return any(term in text for term in terms)
+
+
+def _slash_variants(label: str) -> list[str]:
+    if "/" not in label:
+        return []
+    parts = [part.strip(" -\t") for part in re.split(r"\s*/\s*", label) if part.strip(" -\t")]
+    return parts
+
+
+def _actor_entry(*, label: str, description: str = "", aliases: list[str] | None = None, actor_id: str | None = None, kind: str | None = None, inherits_from: str | None = None) -> dict[str, Any]:
+    clean_label = str(label).strip()
+    validate_canonical_actor_label(clean_label)
+    clean_description = str(description).strip()
+    norm_label = normalize_actor_label(clean_label)
+    dedup_aliases: list[str] = []
+    seen: set[str] = set()
+    for alias in [clean_label, *(aliases or [])]:
+        alias_text = str(alias).strip()
+        alias_norm = normalize_actor_label(alias_text)
+        if not alias_text or not alias_norm or alias_norm in seen:
+            continue
+        seen.add(alias_norm)
+        dedup_aliases.append(alias_text)
+    actor_kind = str(kind or "human").strip().lower() or "human"
+    if actor_kind not in {"human", "system", "consumer"}:
+        raise RuntimeError(f"Actor kind {actor_kind!r} is invalid. Allowed kinds: human, system, consumer.")
+    inherited_actor = str(inherits_from or "").strip() or None
+    return {
+        "id": str(actor_id or norm_label.replace(" ", "_")).strip() or norm_label.replace(" ", "_"),
+        "label": clean_label,
+        "description": clean_description,
+        "kind": actor_kind,
+        "inherits_from": inherited_actor,
+        "aliases": dedup_aliases,
+    }
+
+
+def _markdown_value_to_actor_entry(value: str) -> dict[str, Any]:
+    text = value.strip()
+    if not text:
+        raise RuntimeError("Actor registry entry must not be empty.")
+    match = re.match(r"^(.*?)\s+[—-]\s+(.*)$", text)
+    if match:
+        return _actor_entry(label=match.group(1).strip(), description=match.group(2).strip())
+    if ":" in text:
+        label, description = text.split(":", 1)
+        return _actor_entry(label=label.strip(), description=description.strip())
+    return _actor_entry(label=text)
+
+
+def _repair_actor_label(label: str, *, existing_actors: list[str]) -> tuple[str, str | None]:
+    text = str(label).strip()
+    try:
+        validate_canonical_actor_label(text)
+        return text, None
+    except RuntimeError:
+        pass
+
+    existing_labels = [actor.strip() for actor in existing_actors if actor.strip()]
+    existing_norms = {normalize_actor_label(actor): actor for actor in existing_labels}
+    norm = normalize_actor_label(text)
+    manager_labels = [actor for actor in existing_labels if "manager" in normalize_actor_label(actor)]
+    if manager_labels and "manager" in norm:
+        super_like = {"super", "org wide", "org-wide", "all groups", "all group", "global"}
+        if _contains_any(norm, super_like):
+            for actor in manager_labels:
+                if "super manager" in normalize_actor_label(actor):
+                    return actor, f"repaired {text!r} to existing canonical manager role {actor!r}"
+        for actor in manager_labels:
+            if "regular manager" in normalize_actor_label(actor):
+                return actor, f"repaired {text!r} to existing canonical manager role {actor!r}"
+        if len(manager_labels) == 1:
+            return manager_labels[0], f"repaired {text!r} to existing canonical manager role {manager_labels[0]!r}"
+
+    variants = _slash_variants(text)
+    for variant in sorted(variants, key=lambda item: len(normalize_actor_label(item).split()), reverse=True):
+        variant_norm = normalize_actor_label(variant)
+        if variant_norm in existing_norms:
+            repaired = existing_norms[variant_norm]
+            return repaired, f"repaired {text!r} to existing canonical actor {repaired!r}"
+
+    generic_terms = {"admin", "administrator", "user", "operator", "team", "org", "organization", "level"}
+    if variants:
+        ranked = sorted(
+            variants,
+            key=lambda item: (
+                -len([tok for tok in normalize_actor_label(item).split() if tok not in generic_terms]),
+                -len(normalize_actor_label(item).split()),
+            ),
+        )
+        repaired = ranked[0].strip()
+        validate_canonical_actor_label(repaired)
+        return repaired, f"repaired slash-merged actor {text!r} to canonical actor {repaired!r}"
+
+    raise RuntimeError(
+        f"Canonical actor label {text!r} is invalid and could not be repaired to an existing or canonical actor label."
+    )
+
+
+def _load_json_registry(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    raw_actors = payload.get("actors") if isinstance(payload, dict) else None
+    raw_notes = payload.get("notes") if isinstance(payload, dict) else None
+    actors: list[dict[str, Any]] = []
+    for item in raw_actors or []:
+        if not isinstance(item, dict):
+            continue
+        actors.append(
+            _actor_entry(
+                label=str(item.get("label") or "").strip(),
+                description=str(item.get("description") or "").strip(),
+                aliases=[str(alias).strip() for alias in (item.get("aliases") or []) if str(alias).strip()],
+                actor_id=str(item.get("id") or "").strip() or None,
+                kind=str(item.get("kind") or "").strip() or None,
+                inherits_from=str(item.get("inherits_from") or "").strip() or None,
+            )
+        )
+    notes = [str(item).strip() for item in (raw_notes or []) if str(item).strip()]
+    return {"path": str(path), "actors": actors, "notes": notes}
+
+
+def _load_markdown_registry(path: Path) -> dict[str, Any]:
+    actors: list[dict[str, Any]] = []
+    notes: list[str] = []
+    if path.exists():
+        section: str | None = None
+        for raw_line in path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+            lowered = line.lower()
+            if lowered.startswith("## "):
+                if "actor" in lowered:
+                    section = "actors"
+                elif "note" in lowered:
+                    section = "notes"
+                else:
+                    section = None
+                continue
+            if not line.startswith("- "):
+                continue
+            value = line[2:].strip()
+            if not value:
+                continue
+            if section == "actors":
+                actors.append(_markdown_value_to_actor_entry(value))
+            elif section == "notes":
+                notes.append(value)
+    return {"path": str(path), "actors": actors, "notes": notes}
+
+
+def load_actor_registry(repo_root: Path) -> dict[str, Any]:
+    json_path = actor_registry_json_path(repo_root)
+    if json_path.exists():
+        return _load_json_registry(json_path)
+    return _load_markdown_registry(actor_registry_markdown_path(repo_root))
+
+
+def write_actor_registry(repo_root: Path, *, actors: list[str] | list[dict[str, Any]], notes: list[str] | None = None) -> Path:
+    path = actor_registry_json_path(repo_root)
+    unique: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for actor in actors:
+        if isinstance(actor, dict):
+            entry = _actor_entry(
+                label=str(actor.get("label") or "").strip(),
+                description=str(actor.get("description") or "").strip(),
+                aliases=[str(alias).strip() for alias in (actor.get("aliases") or []) if str(alias).strip()],
+                actor_id=str(actor.get("id") or "").strip() or None,
+                kind=str(actor.get("kind") or "").strip() or None,
+                inherits_from=str(actor.get("inherits_from") or "").strip() or None,
+            )
+        else:
+            entry = _actor_entry(label=str(actor).strip())
+        norm = normalize_actor_label(str(entry["label"]))
+        if not norm or norm in seen:
+            continue
+        seen.add(norm)
+        unique.append(entry)
+    payload = {
+        "version": 1,
+        "actors": unique,
+        "notes": [str(item).strip() for item in (notes or []) if str(item).strip()],
+    }
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def normalize_idea_actors(*, repo_root: Path, idea_id: str, sufficient_idea: dict[str, Any], existing_registry: dict[str, Any] | None = None) -> dict[str, Any]:
+    del idea_id
+    registry = existing_registry or load_actor_registry(repo_root)
+    actor_entries = [item for item in (registry.get("actors") or []) if isinstance(item, dict)]
+    existing_entries_by_id = {str(item.get("id") or "").strip(): dict(item) for item in actor_entries if str(item.get("id") or "").strip()}
+    idea_actors = _coerce_actor_list(sufficient_idea.get("target_users") or sufficient_idea.get("users"))
+    if not idea_actors:
+        return {
+            "canonical_actors": [str(item.get("label") or "").strip() for item in actor_entries if str(item.get("label") or "").strip()],
+            "resolved_actors": actor_entries,
+            "actors": actor_entries,
+            "additions": [],
+            "repairs": [],
+            "notes": list(registry.get("notes") or []),
+            "path": str(actor_registry_path(repo_root).name),
+        }
+
+    llm_result = _llm_normalize_actor_entries(repo_root=repo_root, idea_actors=idea_actors, existing_entries=actor_entries, sufficient_idea=sufficient_idea)
+    mappings = [item for item in (llm_result.get("mappings") or []) if isinstance(item, dict)]
+    resolved_entries = list(actor_entries)
+    additions: list[str] = []
+    repairs: list[dict[str, str]] = []
+    seen_ids = {str(item.get("id") or "").strip() for item in resolved_entries if str(item.get("id") or "").strip()}
+
+    for mapping in mappings:
+        source_text = str(mapping.get("source_actor_text") or "").strip()
+        decision = str(mapping.get("decision") or "").strip().lower()
+        if decision == "matched":
+            actor_ids = [str(item).strip() for item in (mapping.get("canonical_actor_ids") or []) if str(item).strip()]
+            if not actor_ids:
+                raise RuntimeError(f"Actor normalization returned no canonical_actor_ids for matched source actor {source_text!r}")
+            matched_labels: list[str] = []
+            for actor_id in actor_ids:
+                if actor_id not in existing_entries_by_id:
+                    raise RuntimeError(f"Actor normalization returned unknown canonical_actor_id {actor_id!r} for source actor {source_text!r}")
+                matched = existing_entries_by_id[actor_id]
+                matched_labels.append(str(matched.get("label") or "").strip())
+            repairs.append({"original": source_text, "repaired": ", ".join(matched_labels), "reason": str(mapping.get("rationale") or "semantic match").strip()})
+            continue
+        if decision == "proposed":
+            proposed_actors = [item for item in (mapping.get("proposed_actors") or []) if isinstance(item, dict)]
+            if not proposed_actors:
+                raise RuntimeError(f"Actor normalization returned no proposed_actors for source actor {source_text!r}")
+            proposed_labels: list[str] = []
+            for proposed in proposed_actors:
+                proposed_label = str(proposed.get("proposed_label") or "").strip()
+                proposed_id = str(proposed.get("proposed_id") or "").strip() or normalize_actor_label(proposed_label).replace(" ", "_")
+                entry = _actor_entry(
+                    label=proposed_label,
+                    actor_id=proposed_id,
+                    kind=str(proposed.get("kind") or "human").strip() or None,
+                    inherits_from=str(proposed.get("inherits_from") or "").strip() or None,
+                )
+                proposed_labels.append(entry["label"])
+                if entry["id"] not in seen_ids:
+                    resolved_entries.append(entry)
+                    seen_ids.add(entry["id"])
+                    additions.append(entry["label"])
+            repairs.append({"original": source_text, "repaired": ", ".join(proposed_labels), "reason": str(mapping.get("rationale") or "proposed canonical actor").strip()})
+            continue
+        raise RuntimeError(f"Actor normalization returned invalid decision {decision!r} for source actor {source_text!r}")
+
+    return {
+        "canonical_actors": [str(item.get("label") or "").strip() for item in resolved_entries if str(item.get("label") or "").strip()],
+        "resolved_actors": resolved_entries,
+        "actors": resolved_entries,
+        "additions": additions,
+        "repairs": repairs,
+        "notes": list(registry.get("notes") or []),
+        "path": str(actor_registry_path(repo_root).name),
+    }
+
+def persist_actor_registry_artifact(*, repo_root: Path, idea_id: str, payload: dict[str, Any]) -> Path:
+    idea_dir = get_idea_paths(repo_root, idea_id=idea_id).idea_dir
+    idea_dir.mkdir(parents=True, exist_ok=True)
+    out = idea_dir / "actor_registry.json"
+    out.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return out
+
+
+def resolve_actor_entry(*, actor: str, actor_registry: dict[str, Any]) -> dict[str, Any] | None:
+    norm = normalize_actor_label(actor)
+    if not norm:
+        return None
+    raw_entries = actor_registry.get("resolved_actors") or actor_registry.get("actors") or actor_registry.get("canonical_actors") or []
+    entries: list[dict[str, Any]] = []
+    alias_to_entry: dict[str, dict[str, Any]] = {}
+    for item in raw_entries:
+        if isinstance(item, dict):
+            entry = dict(item)
+            label = str(entry.get("label") or "").strip()
+            aliases = [str(alias).strip() for alias in (entry.get("aliases") or []) if str(alias).strip()]
+        else:
+            label = str(item).strip()
+            aliases = []
+            entry = {"id": normalize_actor_label(label).replace(" ", "_"), "label": label, "description": "", "aliases": [label]}
+        if not label:
+            continue
+        entries.append(entry)
+        for alias in [label, *aliases]:
+            alias_norm = normalize_actor_label(alias)
+            if alias_norm and alias_norm not in alias_to_entry:
+                alias_to_entry[alias_norm] = entry
+    if norm in alias_to_entry:
+        return dict(alias_to_entry[norm])
+    actor_tokens = set(norm.split())
+    fuzzy: list[dict[str, Any]] = []
+    for entry in entries:
+        label_norm = normalize_actor_label(str(entry.get("label") or ""))
+        if not label_norm:
+            continue
+        label_tokens = set(label_norm.split())
+        if norm in label_norm or label_norm in norm or actor_tokens.issubset(label_tokens) or label_tokens.issubset(actor_tokens):
+            fuzzy.append(entry)
+    if len(fuzzy) == 1:
+        return dict(fuzzy[0])
+    return None
+
+
+def upsert_runtime_actor_entry(*, actor: str, actor_registry: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    resolved = resolve_actor_entry(actor=actor, actor_registry=actor_registry)
+    if resolved is not None:
+        return actor_registry, resolved
+    label = str(actor).strip()
+    validate_canonical_actor_label(label)
+    raw_entries = list(actor_registry.get("resolved_actors") or actor_registry.get("actors") or [])
+    new_entry = _actor_entry(label=label)
+    raw_entries.append(new_entry)
+    deduped: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in raw_entries:
+        if not isinstance(item, dict):
+            continue
+        norm = normalize_actor_label(str(item.get("label") or ""))
+        if not norm or norm in seen:
+            continue
+        seen.add(norm)
+        deduped.append(dict(item))
+    updated = {
+        **actor_registry,
+        "resolved_actors": deduped,
+        "actors": deduped,
+        "canonical_actors": [str(item.get("label") or "").strip() for item in deduped if str(item.get("label") or "").strip()],
+    }
+    return updated, new_entry
+
+
+def canonicalize_story_actor(*, actor: str, actor_registry: dict[str, Any]) -> str | None:
+    entry = resolve_actor_entry(actor=actor, actor_registry=actor_registry)
+    return None if entry is None else str(entry.get("label") or "").strip() or None