plm-shared 0.1.0__py3-none-any.whl

plm_shared/__init__.py

@@ -0,0 +1,11 @@
+"""plm-shared — frozen contracts shared across TracePulse PLM product lines.
+
+US-W1.0 (PR-1): the modules in this package publish the Kernel emission
+API surface, idempotency key, capability registry, knowledge envelope,
+trace context, pricing helpers, and artifact-store protocol consumed by
+the rest of Wave 1. Models in `kernel_api`, `idempotency`,
+`knowledge_envelope`, and `capabilities` are frozen — never modified by
+downstream stories — so the rest of the wave can be implemented in
+parallel without contract drift.
+"""
+__version__ = "0.1.0"

plm_shared/_w1_13_backfill.py

@@ -0,0 +1,159 @@
+"""US-W1.13 / Conv I — idempotent backfill of Wave 0 metadata to typed columns.
+
+Private module implementing the actual UPDATE statements + summary
+shape used by the W1.13 backfill. Surfaced at the CLI level by
+``02_App/plm-shared/scripts/backfill_w1_13_typed_columns.py``; the
+audit test (`tests/audit/test_w1_13_backfill.py`) imports
+``run_backfill`` from this module directly.
+
+Walks every `telemetry_events` row whose typed column is NULL,
+reads the equivalent value from `payload` JSONB, writes it into
+the new column. Re-running on a fully-backfilled DB yields zero
+further updates (W1.13 §AC-7 — idempotency).
+
+Runs as `plm_migrator` per migration 0008 + Decision #16:
+`plm_kernel_writer` is REVOKED UPDATE on `telemetry_events` per
+the append-only rule, and a backfill IS an UPDATE. The script
+issues `SET LOCAL ROLE plm_migrator` inside each transaction so
+even a superuser-mode invocation stays faithful to the production
+privilege contract.
+
+llm_calls.pricing_source backfill is NOT covered here — the column
+lives in PG, but pre-0016 telemetry-side rows that carried
+`pricing_source` rode in `telemetry_events.payload`, not
+`llm_calls.payload` (`llm_calls` has no payload JSONB column).
+The legacy backend's SQLite `agent_invocations.metadata.pricing_source`
+column is handled by `02_App/backend/database.py`'s startup
+ALTER-TABLE pattern, not by this PG backfill.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine
+
+
+@dataclass(frozen=True)
+class BackfillSummary:
+    """Per-column rowcounts from a single backfill invocation.
+
+    A second invocation against a fully-backfilled DB returns
+    all-zeros — that's the AC-7 idempotency contract.
+    """
+
+    updated_invocation_kind: int
+    updated_is_eval: int
+    updated_parent_invocation_id: int
+    updated_root_invocation_id: int
+    updated_system_context: int
+
+    @property
+    def total(self) -> int:
+        return (
+            self.updated_invocation_kind
+            + self.updated_is_eval
+            + self.updated_parent_invocation_id
+            + self.updated_root_invocation_id
+            + self.updated_system_context
+        )
+
+
+_INVOCATION_KIND_VALUES = ("user", "system", "hidden_retry", "background")
+
+
+_BACKFILL_INVOCATION_KIND = text("""
+    UPDATE telemetry_events
+    SET invocation_kind = (payload->>'invocation_kind')::invocation_kind_v1
+    WHERE invocation_kind IS NULL
+      AND payload ? 'invocation_kind'
+      AND payload->>'invocation_kind' = ANY(:valid_kinds)
+""")
+
+# `is_eval` is non-nullable with default `false`. The migration
+# already populated every legacy row to `false` via the server
+# default; the only useful UPDATE is for rows whose payload
+# explicitly carries `is_eval=true`. Idempotent: re-run on a
+# flipped row no-ops because the WHERE filters it out.
+_BACKFILL_IS_EVAL = text("""
+    UPDATE telemetry_events
+    SET is_eval = true
+    WHERE is_eval = false
+      AND payload ? 'is_eval'
+      AND lower(payload->>'is_eval') IN ('true', '1')
+""")
+
+_BACKFILL_PARENT_INVOCATION_ID = text("""
+    UPDATE telemetry_events
+    SET parent_invocation_id = (payload->>'parent_invocation_id')::uuid
+    WHERE parent_invocation_id IS NULL
+      AND payload ? 'parent_invocation_id'
+      AND payload->>'parent_invocation_id' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+""")
+
+_BACKFILL_ROOT_INVOCATION_ID = text("""
+    UPDATE telemetry_events
+    SET root_invocation_id = (payload->>'root_invocation_id')::uuid
+    WHERE root_invocation_id IS NULL
+      AND payload ? 'root_invocation_id'
+      AND payload->>'root_invocation_id' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+""")
+
+_BACKFILL_SYSTEM_CONTEXT = text("""
+    UPDATE telemetry_events
+    SET system_context = payload->>'system_context'
+    WHERE system_context IS NULL
+      AND payload ? 'system_context'
+""")
+
+
+def run_backfill(engine: Engine) -> BackfillSummary:
+    """Apply every per-column backfill UPDATE; return a counts summary.
+
+    Each UPDATE runs in its own transaction so a partial failure
+    on one column doesn't roll back successful work on previous
+    columns. `SET LOCAL ROLE plm_migrator` is issued inside each
+    transaction so the privilege check happens even when the
+    connecting user is the dev superuser. Idempotent — every
+    WHERE clause filters rows that already have the typed column
+    populated.
+    """
+    counts = {}
+    for label, statement in (
+        ("invocation_kind", _BACKFILL_INVOCATION_KIND),
+        ("is_eval", _BACKFILL_IS_EVAL),
+        ("parent_invocation_id", _BACKFILL_PARENT_INVOCATION_ID),
+        ("root_invocation_id", _BACKFILL_ROOT_INVOCATION_ID),
+        ("system_context", _BACKFILL_SYSTEM_CONTEXT),
+    ):
+        with engine.begin() as conn:
+            conn.execute(text("SET LOCAL ROLE plm_migrator"))
+            params = (
+                {"valid_kinds": list(_INVOCATION_KIND_VALUES)}
+                if label == "invocation_kind"
+                else {}
+            )
+            result = conn.execute(statement, params)
+            counts[label] = result.rowcount or 0
+
+    return BackfillSummary(
+        updated_invocation_kind=counts["invocation_kind"],
+        updated_is_eval=counts["is_eval"],
+        updated_parent_invocation_id=counts["parent_invocation_id"],
+        updated_root_invocation_id=counts["root_invocation_id"],
+        updated_system_context=counts["system_context"],
+    )
+
+
+def build_engine_from_env(dsn: Optional[str] = None) -> Engine:
+    """Resolve `PG_DSN` from env (or the explicit override) and bind."""
+    url = (dsn or os.environ.get("PG_DSN", "")).strip()
+    if not url:
+        raise RuntimeError(
+            "PG_DSN is not set. Export it before running the W1.13 "
+            "backfill (e.g. "
+            "`postgresql+psycopg://tracepulse:tracepulse@localhost:5432/tracepulse_dev`)."
+        )
+    return create_engine(url, future=True)

plm_shared/agents/__init__.py

@@ -0,0 +1,14 @@
+"""Lifted ``agents/`` modules (Wave 6.7 Conv A).
+
+Per Decision #177 — these are not Protocol indirections; they are the
+**canonical** homes of ``BaseAgent`` (abstract base class for the multi-
+agent PDF→BPMN chain), the domain classifier / RACI extractor, and the
+domain-specific prompt prefixes. Lifted from
+``02_App/backend/agents/`` via ``git mv`` so sibling packages
+(:mod:`plm_skill_packages`) can import them without depending on
+``02_App/backend/``.
+
+The legacy paths under ``02_App/backend/agents/`` remain as thin
+re-export shims for the duration of the DC-1 90-day soak, matching the
+W1.4 RunTaskTracker + Wave 6.5 Conv A/B precedent.
+"""

plm_shared/agents/base_agent.py

@@ -0,0 +1,110 @@
+"""
+Base Agent Abstract Class
+Defines the interface for all agents in the system.
+All agents must inherit from this class and implement execute() and validate_input().
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all agents.
+    
+    Provides:
+    - Unified interface (execute, validate_input, get_output_schema)
+    - Metadata tracking
+    - Structured logging
+    - NO timeout (long operations allowed)
+    """
+    
+    def __init__(self, name: str, description: str = ""):
+        """
+        Initialize agent.
+
+        Args:
+            name: Agent unique identifier (e.g., "plm_orchestrator")
+            description: Human-readable description
+
+        Note:
+            US-471.11 dropped the `model_id` constructor parameter — it was
+            assigned but never read at dispatch time. The runtime model id is
+            sourced from `Agent.model_id` (DB) via `llm_service.generate_*`
+            keyword arguments at the call site.
+        """
+        self.name = name
+        self.description = description
+        self.metadata: Dict[str, Any] = {}
+        self.logger = logging.getLogger(f"agents.{name}")
+    
+    @abstractmethod
+    async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute the agent with given input.
+        
+        Args:
+            input_data: Dictionary with required fields for this agent
+        
+        Returns:
+            Dictionary with results (structure depends on agent)
+        
+        Note:
+            - Can take arbitrary time (no timeout)
+            - Must handle errors gracefully
+            - Must return a dictionary (even on error, return {"error": str})
+        """
+        pass
+    
+    def validate_input(self, input_data: Dict[str, Any]) -> bool:
+        """
+        Validate if input_data has required fields for this agent.
+        
+        Args:
+            input_data: Input dictionary to validate
+        
+        Returns:
+            True if valid, False otherwise
+        """
+        # Default: always valid (override in subclasses)
+        return True
+    
+    def get_required_fields(self) -> list[str]:
+        """
+        Get list of required input fields.
+        
+        Returns:
+            List of field names required by validate_input()
+        """
+        return []
+    
+    def get_output_schema(self) -> Dict[str, Any]:
+        """
+        Get JSON schema for agent output.
+        
+        Returns:
+            JSON schema describing output structure
+        """
+        return {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": True
+        }
+    
+    def get_metadata(self) -> Dict[str, Any]:
+        """Get agent metadata (execution stats, etc.)."""
+        return self.metadata.copy()
+    
+    def _log_execution(self, status: str, message: str = "", error: Optional[str] = None):
+        """Log agent execution event."""
+        if status == "start":
+            self.logger.info(f"Agent {self.name} starting execution. {message}")
+        elif status == "success":
+            self.logger.info(f"Agent {self.name} completed successfully. {message}")
+        elif status == "error":
+            self.logger.error(f"Agent {self.name} failed: {error}. {message}")
+        elif status == "warning":
+            self.logger.warning(f"Agent {self.name} warning: {message}")

plm_shared/agents/domain_classifier.py

@@ -0,0 +1,86 @@
+"""
+Domain Classifier Agent
+Classifies document domain (PLM, QMS, IT, generic) and detects RACI matrices.
+Lightweight single LLM call on first 2000 chars of document.
+"""
+
+from typing import Dict, Any
+import json
+import logging
+
+from plm_shared.protocols.services.llm import llm_service
+
+logger = logging.getLogger(__name__)
+
+CLASSIFIER_PROMPT = """You are a Document Domain Classifier. Analyze the document excerpt and determine:
+
+1. The business domain:
+   - "plm": Product Lifecycle Management, engineering, manufacturing, CAD/CAM, BOM, ECO, work instructions, production
+   - "qms": Quality Management System, ISO 9001, document control, audit, compliance, quality policy
+   - "it": IT processes, ITIL, DevOps, software development, CI/CD, incident management
+   - "generic": General business process not fitting above categories
+
+2. Whether the document contains a RACI matrix (Responsible, Accountable, Consulted, Informed)
+
+3. Key standards, personas, and systems mentioned in the document
+
+Be precise. Choose the single best-matching domain based on the document's primary topic."""
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "domain": {"type": "string", "enum": ["plm", "qms", "it", "generic"]},
+        "domain_label": {"type": "string", "description": "Human-readable domain label, e.g. 'Quality Management System (ISO 9001)'"},
+        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+        "has_raci": {"type": "boolean", "description": "Whether the document contains a RACI matrix"},
+        "raci_section": {"type": "string", "description": "Section name/number containing the RACI matrix, or empty if none"},
+        "key_standards": {"type": "array", "items": {"type": "string"}, "description": "Standards referenced (e.g. ISO 9001:2015, AS9100)"},
+        "key_personas": {"type": "array", "items": {"type": "string"}, "description": "Key roles/personas mentioned"},
+        "key_systems": {"type": "array", "items": {"type": "string"}, "description": "Key IT/software systems mentioned"},
+    },
+    "required": ["domain", "domain_label", "confidence", "has_raci"],
+}
+
+
+async def classify_domain(document_excerpt: str) -> Dict[str, Any]:
+    """
+    Classify the domain of a document from its first ~2000 characters.
+
+    Returns dict with domain, confidence, has_raci, key_personas, key_systems, etc.
+    """
+    print("[DOMAIN CLASSIFIER] Analyzing document domain...")
+
+    try:
+        result = await llm_service.generate_structured(
+            system_prompt=CLASSIFIER_PROMPT,
+            user_prompt=f"Classify this document:\n\n{document_excerpt[:2000]}",
+            output_schema=OUTPUT_SCHEMA,
+            temperature=0.1,
+        )
+
+        domain = result.get("domain", "generic")
+        label = result.get("domain_label", domain)
+        confidence = result.get("confidence", 0.5)
+        has_raci = result.get("has_raci", False)
+
+        print(f"[DOMAIN CLASSIFIER] Domain: {label} (confidence: {confidence:.0%})")
+        if has_raci:
+            print(f"[DOMAIN CLASSIFIER] RACI matrix detected in: {result.get('raci_section', '?')}")
+        print(f"[DOMAIN CLASSIFIER] Personas: {result.get('key_personas', [])}")
+        print(f"[DOMAIN CLASSIFIER] Systems: {result.get('key_systems', [])}")
+
+        return result
+
+    except Exception as e:
+        logger.warning(f"Domain classification failed: {e}")
+        print(f"[DOMAIN CLASSIFIER] Failed: {e} — defaulting to 'plm'")
+        return {
+            "domain": "plm",
+            "domain_label": "PLM (default fallback)",
+            "confidence": 0.0,
+            "has_raci": False,
+            "raci_section": "",
+            "key_standards": [],
+            "key_personas": [],
+            "key_systems": [],
+        }

plm_shared/agents/domain_prompts.py

@@ -0,0 +1,99 @@
+"""
+Domain-specific prompt prefixes for PLM extraction agents.
+Injected before existing agent prompts based on document domain classification.
+"""
+
+from typing import Dict
+
+DOMAIN_CONTEXT: Dict[str, Dict[str, str]] = {
+    "plm": {
+        "agent1_prefix": "",
+        "agent2_prefix": "",
+        "agent3_prefix": "",
+        "agent5_prefix": "",
+    },
+    "qms": {
+        "agent1_prefix": """DOMAIN CONTEXT — QUALITY MANAGEMENT SYSTEM (QMS)
+This document describes a QMS process (likely ISO 9001 compliant).
+Personas to look for: Document Owner, Reviewer(s), Approver, Quality Manager, Document Control, Users/Stakeholders, Process Owner, Auditor.
+Systems to look for: Controlled Document Repository, Master Document List, Document Management System (DMS), ECM, SharePoint, Quality Record Archive.
+Sections typically include: Purpose, Scope, Roles & Responsibilities, Detailed Process Description, RACI Matrix, Records, Risk Considerations, Document Control, Version History.
+Do NOT default to PLM personas (Configuration Methods Agent, Production Manager) unless explicitly mentioned.
+""",
+        "agent2_prefix": """DOMAIN CONTEXT — QMS DOCUMENT
+This is a QMS document following ISO 9001 structure. Process steps are in numbered sections (e.g., 6.1, 6.2, ..., 6.11).
+CRITICAL: Each numbered sub-section (6.1, 6.2, etc.) IS a distinct process step. Do NOT merge them into fewer steps.
+Preserve the exact section numbering and titles in the process block names.
+Look for: review cycles, approval workflows, document lifecycle states (Draft → Review → Approved → Released → Obsolete).
+Assign HIGH confidence (0.9+) to clearly numbered sub-process sections with detailed step descriptions.
+""",
+        "agent3_prefix": """DOMAIN CONTEXT — QMS PROCESS MODELING
+Use QMS-specific personas from the document (Document Owner, Reviewer, Approver, Quality Manager, Users).
+Do NOT substitute PLM personas (Configuration Methods Agent, Quality Inspector, Manufacturing Engineer) unless they are explicitly mentioned in the source document.
+Decision points in QMS processes include: adequacy review pass/fail, approval granted/rejected, compliance check pass/fail.
+Reference applicable standards (ISO 9001, clause numbers) in task descriptions when the source document mentions them.
+Do NOT inject PLM-specific terminology (BOM, ECO, FAI, SAP routings) unless explicitly present in the source text.
+""",
+        "agent5_prefix": """DOMAIN CONTEXT — QMS VALIDATION
+This is a QMS process, NOT a PLM/manufacturing process.
+Score PERTINENCE based on QMS best practices (ISO 9001 document control, compliance workflows), not PLM methodology.
+A well-modeled QMS process IS pertinent — do NOT penalize it for not following PLM patterns (gates, phases, engineering reviews).
+Expected keywords for QMS: "document-control", "review-approval", "compliance", "quality-management", "ISO-9001", "release", "obsolescence".
+A complete and well-structured QMS process should score 0.8+ on pertinence.
+""",
+    },
+    "it": {
+        "agent1_prefix": """DOMAIN CONTEXT — IT / ITSM PROCESS
+This document describes an IT or IT Service Management process (possibly ITIL-aligned).
+Personas to look for: Service Owner, Incident Manager, Change Manager, Release Manager, Developer, Operations Engineer, End User, CAB (Change Advisory Board).
+Systems to look for: ServiceNow, Jira, CI/CD Pipeline, Monitoring tools (Datadog, Grafana), CMDB, Git, Jenkins, Kubernetes.
+""",
+        "agent2_prefix": """DOMAIN CONTEXT — IT PROCESS DOCUMENT
+Look for ITIL-style process flows: incident management, change management, release management, problem management.
+Process steps may be organized by ticket lifecycle states, sprint phases, or deployment stages.
+Assign HIGH confidence to clearly documented runbooks, playbooks, or SOPs with numbered steps.
+""",
+        "agent3_prefix": """DOMAIN CONTEXT — IT PROCESS MODELING
+Use IT-specific personas and systems from the document.
+Decision points include: CAB approval, deployment go/no-go, rollback decisions, SLA breach escalation.
+Do NOT inject PLM or manufacturing terminology unless explicitly present in the source.
+""",
+        "agent5_prefix": """DOMAIN CONTEXT — IT PROCESS VALIDATION
+This is an IT process, not PLM or QMS.
+Score PERTINENCE based on IT best practices (ITIL, DevOps), not PLM methodology.
+Expected keywords: "incident-management", "change-management", "deployment", "monitoring", "SLA", "ITIL".
+""",
+    },
+    "generic": {
+        "agent1_prefix": """DOMAIN CONTEXT — GENERAL BUSINESS PROCESS
+This document describes a general business process. Extract personas, systems, and process steps as described.
+Do not assume any specific domain terminology. Use the personas and systems explicitly mentioned in the document.
+""",
+        "agent2_prefix": """DOMAIN CONTEXT — GENERAL BUSINESS DOCUMENT
+Extract process steps as described in the document without domain-specific assumptions.
+Numbered sections or bullet lists describing sequential activities are process steps.
+""",
+        "agent3_prefix": """DOMAIN CONTEXT — GENERAL PROCESS MODELING
+Use personas and systems exactly as mentioned in the source document.
+Do NOT inject domain-specific terminology (PLM, QMS, ITIL) unless present in the source.
+""",
+        "agent5_prefix": """DOMAIN CONTEXT — GENERAL PROCESS VALIDATION
+This is a general business process. Score PERTINENCE based on general business process quality.
+Do NOT penalize for not following PLM-specific methodology.
+""",
+    },
+}
+
+
+def get_domain_prefix(domain: str, agent_key: str) -> str:
+    """Get the domain-specific prompt prefix for a given agent.
+
+    Args:
+        domain: Domain identifier (plm, qms, it, generic)
+        agent_key: Agent prefix key (agent1_prefix, agent2_prefix, agent3_prefix, agent5_prefix)
+
+    Returns:
+        Prompt prefix string (empty for PLM domain since prompts are already PLM-oriented)
+    """
+    ctx = DOMAIN_CONTEXT.get(domain, DOMAIN_CONTEXT["generic"])
+    return ctx.get(agent_key, "")

plm_shared/agents/raci_extractor.py

@@ -0,0 +1,80 @@
+"""
+RACI Matrix Extractor Agent
+Extracts RACI assignments from a document when a RACI matrix is detected.
+"""
+
+from typing import Dict, Any, List
+import logging
+
+from plm_shared.protocols.services.llm import llm_service
+
+logger = logging.getLogger(__name__)
+
+RACI_PROMPT = """You are a RACI Matrix Extraction Specialist. Extract the RACI matrix from the document.
+
+For each sub-process or activity row in the RACI table, extract:
+- The sub-process identifier and name (e.g. "6.1 Need Identification")
+- The RACI assignments for each role/persona
+
+RACI values:
+- "R" = Responsible (does the work)
+- "A" = Accountable (owns the outcome, signs off)
+- "C" = Consulted (provides input before)
+- "I" = Informed (notified after)
+
+For combined values like "A/R", use the PRIMARY role (the first one listed).
+If a cell is empty or has no assignment, omit that persona.
+
+Extract EVERY row from the RACI table. Do not skip or merge rows."""
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "raci_entries": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "sub_process": {"type": "string", "description": "Sub-process name, e.g. '6.1 Need Identification'"},
+                    "assignments": {
+                        "type": "object",
+                        "additionalProperties": {"type": "string", "enum": ["R", "A", "C", "I"]},
+                        "description": "Mapping of persona name to RACI role",
+                    },
+                },
+                "required": ["sub_process", "assignments"],
+            },
+        },
+    },
+    "required": ["raci_entries"],
+}
+
+
+async def extract_raci(document_text: str) -> Dict[str, Any]:
+    """
+    Extract RACI matrix from document text.
+
+    Returns dict with raci_entries list.
+    """
+    print("[RACI EXTRACTOR] Extracting RACI matrix...")
+
+    try:
+        result = await llm_service.generate_structured(
+            system_prompt=RACI_PROMPT,
+            user_prompt=f"Extract the RACI matrix from this document:\n\n{document_text}",
+            output_schema=OUTPUT_SCHEMA,
+            temperature=0.1,
+        )
+
+        entries = result.get("raci_entries", [])
+        print(f"[RACI EXTRACTOR] Extracted {len(entries)} RACI entries")
+        for entry in entries:
+            roles = ", ".join(f"{k}={v}" for k, v in entry.get("assignments", {}).items())
+            print(f"  - {entry.get('sub_process', '?')}: {roles}")
+
+        return result
+
+    except Exception as e:
+        logger.warning(f"RACI extraction failed: {e}")
+        print(f"[RACI EXTRACTOR] Failed: {e}")
+        return {"raci_entries": []}