hyperagents 1.2.3rc5.post3__py3-none-any.whl

civilization/interview/interviewer.py

@@ -0,0 +1,323 @@
+"""
+Interactive interviewer for knowledge elicitation.
+Guides users through structured interviews to capture organizational knowledge.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable
+from uuid import UUID, uuid4
+
+from ..schema import NodeType, CivilizationNode
+
+logger = logging.getLogger(__name__)
+
+
+class InterviewState(str, Enum):
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    ABANDONED = "abandoned"
+
+
+@dataclass
+class InterviewResponse:
+    """A single response in an interview."""
+    question_id: str
+    question_text: str
+    response_text: str
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    confidence: float | None = None
+    follow_up_needed: bool = False
+    extracted_entities: list[str] = field(default_factory=list)
+
+
+@dataclass
+class InterviewSession:
+    """Represents an interview session."""
+    id: UUID = field(default_factory=uuid4)
+    org_id: str = ""
+    target_node_type: NodeType = NodeType.SOP
+    subject: str = ""
+    interviewer_id: str | None = None
+    interviewee_id: str | None = None
+    state: InterviewState = InterviewState.NOT_STARTED
+    responses: list[InterviewResponse] = field(default_factory=list)
+    current_question_index: int = 0
+    total_questions: int = 0
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def progress(self) -> float:
+        """Return progress as percentage (0-100)."""
+        if self.total_questions == 0:
+            return 0.0
+        return (len(self.responses) / self.total_questions) * 100
+
+    @property
+    def duration_minutes(self) -> float | None:
+        """Return interview duration in minutes."""
+        if not self.started_at:
+            return None
+        end = self.completed_at or datetime.utcnow()
+        return (end - self.started_at).total_seconds() / 60
+
+
+class InterviewTemplate:
+    """Template for a specific type of interview."""
+
+    def __init__(self, node_type: NodeType, questions: list[dict]):
+        self.node_type = node_type
+        self.questions = questions
+
+    @classmethod
+    def for_sop(cls) -> "InterviewTemplate":
+        """Create template for SOP interviews."""
+        return cls(NodeType.SOP, [
+            {"id": "sop_name", "text": "What is the name of this procedure?", "required": True},
+            {"id": "sop_purpose", "text": "What is the purpose of this SOP? What problem does it solve?", "required": True},
+            {"id": "sop_scope", "text": "What is the scope? What does this SOP cover and not cover?", "required": True},
+            {"id": "sop_trigger", "text": "What triggers this procedure? When should someone start it?", "required": True},
+            {"id": "sop_roles", "text": "Who is involved in this procedure? What roles are needed?", "required": True},
+            {"id": "sop_steps", "text": "Walk me through the steps. What happens first, second, etc.?", "required": True},
+            {"id": "sop_tools", "text": "What tools or systems are used in this procedure?", "required": False},
+            {"id": "sop_duration", "text": "How long does this procedure typically take?", "required": False},
+            {"id": "sop_failure", "text": "What happens if something goes wrong? How do you handle failures?", "required": False},
+            {"id": "sop_success", "text": "How do you know the procedure was successful? What are the success criteria?", "required": True},
+            {"id": "sop_exceptions", "text": "Are there any exceptions or edge cases to be aware of?", "required": False},
+            {"id": "sop_related", "text": "Are there other procedures that relate to this one?", "required": False},
+        ])
+
+    @classmethod
+    def for_role(cls) -> "InterviewTemplate":
+        """Create template for role interviews."""
+        return cls(NodeType.ROLE, [
+            {"id": "role_title", "text": "What is the title of this role?", "required": True},
+            {"id": "role_department", "text": "Which department or team does this role belong to?", "required": True},
+            {"id": "role_mission", "text": "What is the primary mission or purpose of this role?", "required": True},
+            {"id": "role_responsibilities", "text": "What are the key responsibilities of this role?", "required": True},
+            {"id": "role_accountabilities", "text": "What outcomes is this role accountable for?", "required": True},
+            {"id": "role_authority", "text": "What decisions can this role make independently?", "required": True},
+            {"id": "role_escalation", "text": "Who does this role escalate issues to?", "required": True},
+            {"id": "role_interfaces", "text": "Which other roles or teams does this role regularly interact with?", "required": True},
+            {"id": "role_tools", "text": "What tools and systems does this role use daily?", "required": False},
+            {"id": "role_sops", "text": "What SOPs or procedures does this role own or follow?", "required": False},
+        ])
+
+    @classmethod
+    def for_checklist(cls) -> "InterviewTemplate":
+        """Create template for checklist interviews."""
+        return cls(NodeType.CHECKLIST, [
+            {"id": "cl_name", "text": "What is this checklist called?", "required": True},
+            {"id": "cl_purpose", "text": "What is the purpose of this checklist?", "required": True},
+            {"id": "cl_trigger", "text": "When should this checklist be used?", "required": True},
+            {"id": "cl_frequency", "text": "How often is this checklist used? (daily, weekly, per-event, etc.)", "required": False},
+            {"id": "cl_items", "text": "Walk me through each item on the checklist.", "required": True},
+            {"id": "cl_verification", "text": "How do you verify each item is complete?", "required": False},
+            {"id": "cl_responsible", "text": "Who is responsible for completing this checklist?", "required": True},
+            {"id": "cl_related_sop", "text": "Is this checklist part of a larger SOP?", "required": False},
+        ])
+
+    @classmethod
+    def get_template(cls, node_type: NodeType) -> "InterviewTemplate":
+        """Get the appropriate template for a node type."""
+        templates = {
+            NodeType.SOP: cls.for_sop,
+            NodeType.ROLE: cls.for_role,
+            NodeType.CHECKLIST: cls.for_checklist,
+        }
+        factory = templates.get(node_type, cls.for_sop)
+        return factory()
+
+
+class Interviewer:
+    """
+    Conducts structured interviews to elicit organizational knowledge.
+    Supports asynchronous, multi-session interviews.
+    """
+
+    def __init__(
+        self,
+        org_id: str,
+        store=None,  # CivilizationStore
+        llm_callback: Callable[[str], str] | None = None,
+    ):
+        self.org_id = org_id
+        self.store = store
+        self.llm_callback = llm_callback
+        self.sessions: dict[UUID, InterviewSession] = {}
+
+    def start_session(
+        self,
+        target_node_type: NodeType,
+        subject: str,
+        interviewee_id: str | None = None,
+    ) -> InterviewSession:
+        """Start a new interview session."""
+        template = InterviewTemplate.get_template(target_node_type)
+
+        session = InterviewSession(
+            org_id=self.org_id,
+            target_node_type=target_node_type,
+            subject=subject,
+            interviewee_id=interviewee_id,
+            state=InterviewState.IN_PROGRESS,
+            total_questions=len(template.questions),
+            started_at=datetime.utcnow(),
+        )
+
+        self.sessions[session.id] = session
+        return session
+
+    def get_current_question(self, session_id: UUID) -> dict | None:
+        """Get the current question for a session."""
+        session = self.sessions.get(session_id)
+        if not session or session.state != InterviewState.IN_PROGRESS:
+            return None
+
+        template = InterviewTemplate.get_template(session.target_node_type)
+        if session.current_question_index >= len(template.questions):
+            return None
+
+        return template.questions[session.current_question_index]
+
+    def submit_response(
+        self,
+        session_id: UUID,
+        response_text: str,
+        confidence: float | None = None,
+    ) -> dict:
+        """
+        Submit a response to the current question.
+
+        Returns:
+            Dict with: next_question, is_complete, follow_up
+        """
+        session = self.sessions.get(session_id)
+        if not session or session.state != InterviewState.IN_PROGRESS:
+            return {"error": "Invalid session or session not in progress"}
+
+        template = InterviewTemplate.get_template(session.target_node_type)
+        if session.current_question_index >= len(template.questions):
+            return {"error": "No more questions"}
+
+        current_q = template.questions[session.current_question_index]
+
+        # Record response
+        response = InterviewResponse(
+            question_id=current_q["id"],
+            question_text=current_q["text"],
+            response_text=response_text,
+            confidence=confidence,
+        )
+        session.responses.append(response)
+        session.current_question_index += 1
+
+        # Check if interview is complete
+        if session.current_question_index >= len(template.questions):
+            session.state = InterviewState.COMPLETED
+            session.completed_at = datetime.utcnow()
+            return {
+                "is_complete": True,
+                "next_question": None,
+                "progress": 100.0,
+            }
+
+        next_q = template.questions[session.current_question_index]
+        return {
+            "is_complete": False,
+            "next_question": next_q,
+            "progress": session.progress,
+        }
+
+    def pause_session(self, session_id: UUID) -> bool:
+        """Pause an interview session."""
+        session = self.sessions.get(session_id)
+        if session and session.state == InterviewState.IN_PROGRESS:
+            session.state = InterviewState.PAUSED
+            return True
+        return False
+
+    def resume_session(self, session_id: UUID) -> InterviewSession | None:
+        """Resume a paused interview session."""
+        session = self.sessions.get(session_id)
+        if session and session.state == InterviewState.PAUSED:
+            session.state = InterviewState.IN_PROGRESS
+            return session
+        return None
+
+    def abandon_session(self, session_id: UUID) -> bool:
+        """Abandon an interview session."""
+        session = self.sessions.get(session_id)
+        if session:
+            session.state = InterviewState.ABANDONED
+            return True
+        return False
+
+    def get_session(self, session_id: UUID) -> InterviewSession | None:
+        """Get a session by ID."""
+        return self.sessions.get(session_id)
+
+    def compile_to_node(self, session_id: UUID) -> CivilizationNode | None:
+        """
+        Compile interview responses into a CivilizationNode.
+        Only works for completed sessions.
+        """
+        session = self.sessions.get(session_id)
+        if not session or session.state != InterviewState.COMPLETED:
+            return None
+
+        # Build response lookup
+        responses = {r.question_id: r.response_text for r in session.responses}
+
+        if session.target_node_type == NodeType.SOP:
+            from ..schema import SOP, SOPStep
+            return SOP(
+                org_id=session.org_id,
+                title=responses.get("sop_name", session.subject),
+                purpose=responses.get("sop_purpose", ""),
+                scope=responses.get("sop_scope", ""),
+                triggers=[responses.get("sop_trigger", "")] if responses.get("sop_trigger") else [],
+                steps=self._parse_steps(responses.get("sop_steps", "")),
+                roles_involved=self._parse_list(responses.get("sop_roles", "")),
+                tools_required=self._parse_list(responses.get("sop_tools", "")),
+                success_criteria=self._parse_list(responses.get("sop_success", "")),
+                metadata={"source": "interview", "session_id": str(session.id)},
+            )
+
+        # Add more node type compilations as needed
+        return None
+
+    def _parse_steps(self, text: str) -> list:
+        """Parse step descriptions into SOPStep objects."""
+        from ..schema import SOPStep
+        if not text:
+            return []
+
+        # Simple parsing: split by numbered items or newlines
+        lines = [l.strip() for l in text.split("\n") if l.strip()]
+        steps = []
+        for i, line in enumerate(lines, 1):
+            # Remove leading numbers/bullets
+            import re
+            cleaned = re.sub(r"^[\d\.\)\-\*]+\s*", "", line)
+            if cleaned:
+                steps.append(SOPStep(
+                    step_number=i,
+                    title=f"Step {i}",
+                    description=cleaned,
+                ))
+        return steps if steps else [SOPStep(step_number=1, title="Step 1", description=text)]
+
+    def _parse_list(self, text: str) -> list[str]:
+        """Parse comma or newline separated list."""
+        if not text:
+            return []
+        import re
+        items = re.split(r"[,\n]", text)
+        return [item.strip() for item in items if item.strip()]

civilization/interview/questioner.py

@@ -0,0 +1,363 @@
+"""
+Dynamic question generation for knowledge elicitation.
+Generates contextual follow-up questions based on responses and gaps.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+from uuid import UUID, uuid4
+
+from ..schema import NodeType, CivilizationNode
+
+logger = logging.getLogger(__name__)
+
+
+class QuestionType(str, Enum):
+    OPEN = "open"  # Open-ended questions
+    CLOSED = "closed"  # Yes/No questions
+    MULTIPLE_CHOICE = "multiple_choice"
+    SCALE = "scale"  # 1-5 or 1-10 ratings
+    LIST = "list"  # Ask for a list of items
+    CLARIFICATION = "clarification"  # Follow-up for unclear answers
+    CONFIRMATION = "confirmation"  # Verify understanding
+
+
+class QuestionPriority(str, Enum):
+    REQUIRED = "required"
+    RECOMMENDED = "recommended"
+    OPTIONAL = "optional"
+
+
+@dataclass
+class Question:
+    """Represents a question to ask during knowledge elicitation."""
+    id: str
+    text: str
+    question_type: QuestionType = QuestionType.OPEN
+    priority: QuestionPriority = QuestionPriority.REQUIRED
+    context: str | None = None
+    options: list[str] = field(default_factory=list)  # For multiple choice
+    follow_up_for: str | None = None  # ID of question this follows up on
+    validation_hint: str | None = None
+    examples: list[str] = field(default_factory=list)
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class QuestionContext:
+    """Context for generating questions."""
+    target_node_type: NodeType
+    subject: str
+    existing_responses: dict[str, str] = field(default_factory=dict)
+    existing_nodes: list[CivilizationNode] = field(default_factory=list)
+    detected_gaps: list[str] = field(default_factory=list)
+    interview_depth: str = "standard"  # "brief", "standard", "thorough"
+
+
+class Questioner:
+    """
+    Generates dynamic questions for knowledge elicitation.
+    Adapts questions based on context, previous responses, and detected gaps.
+    """
+
+    def __init__(
+        self,
+        llm_callback: Callable[[str, str], str] | None = None,
+    ):
+        self.llm_callback = llm_callback
+        self._question_templates = self._load_templates()
+
+    def _load_templates(self) -> dict[NodeType, list[Question]]:
+        """Load question templates for each node type."""
+        return {
+            NodeType.SOP: [
+                Question(
+                    id="sop_overview",
+                    text="Can you give me a high-level overview of this procedure?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                    context="Start with the big picture before diving into details",
+                ),
+                Question(
+                    id="sop_trigger",
+                    text="What events or conditions trigger this procedure?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.REQUIRED,
+                    examples=["Customer complaint received", "Monthly audit due", "New employee onboarding"],
+                ),
+                Question(
+                    id="sop_prerequisites",
+                    text="What needs to be in place before starting this procedure?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+                Question(
+                    id="sop_first_step",
+                    text="What is the very first thing someone does when starting this procedure?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="sop_decision_points",
+                    text="Are there any decision points where the procedure can branch?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.RECOMMENDED,
+                    context="We want to capture if-then logic in the procedure",
+                ),
+                Question(
+                    id="sop_handoffs",
+                    text="Are there any handoffs between people or teams during this procedure?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+                Question(
+                    id="sop_failure_modes",
+                    text="What are the most common ways this procedure can fail?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+                Question(
+                    id="sop_time_critical",
+                    text="Are there any time-sensitive steps or SLAs to be aware of?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.OPTIONAL,
+                ),
+            ],
+            NodeType.ROLE: [
+                Question(
+                    id="role_mission",
+                    text="What is the primary mission or purpose of this role?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="role_daily",
+                    text="What does a typical day look like for someone in this role?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="role_decisions",
+                    text="What decisions can this role make independently?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="role_escalation",
+                    text="What situations require escalation? To whom?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="role_interfaces",
+                    text="Which other roles or teams does this role interact with most?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+                Question(
+                    id="role_success",
+                    text="How is success measured for this role?",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+            ],
+            NodeType.CHECKLIST: [
+                Question(
+                    id="cl_purpose",
+                    text="What is the purpose of this checklist?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="cl_when",
+                    text="When should this checklist be used?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="cl_items",
+                    text="Walk me through each item on the checklist.",
+                    question_type=QuestionType.LIST,
+                    priority=QuestionPriority.REQUIRED,
+                ),
+                Question(
+                    id="cl_critical",
+                    text="Are any items especially critical? What happens if they're missed?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.RECOMMENDED,
+                ),
+            ],
+        }
+
+    def get_initial_questions(
+        self,
+        context: QuestionContext,
+    ) -> list[Question]:
+        """Get initial questions based on context."""
+        templates = self._question_templates.get(context.target_node_type, [])
+
+        # Filter by depth
+        if context.interview_depth == "brief":
+            return [q for q in templates if q.priority == QuestionPriority.REQUIRED]
+        elif context.interview_depth == "thorough":
+            return templates
+        else:  # standard
+            return [q for q in templates if q.priority != QuestionPriority.OPTIONAL]
+
+    def generate_follow_up(
+        self,
+        question_id: str,
+        response: str,
+        context: QuestionContext,
+    ) -> list[Question]:
+        """Generate follow-up questions based on a response."""
+        follow_ups = []
+
+        # Check for vague responses that need clarification
+        vague_indicators = ["sometimes", "usually", "it depends", "maybe", "i think"]
+        if any(indicator in response.lower() for indicator in vague_indicators):
+            follow_ups.append(Question(
+                id=f"{question_id}_clarify",
+                text="Can you be more specific? In what situations does this vary?",
+                question_type=QuestionType.CLARIFICATION,
+                priority=QuestionPriority.REQUIRED,
+                follow_up_for=question_id,
+            ))
+
+        # Check for mentions of other processes/roles that aren't documented
+        if context.existing_nodes:
+            existing_titles = {n.title.lower() for n in context.existing_nodes}
+            # Simple heuristic: look for capitalized phrases that might be references
+            import re
+            potential_refs = re.findall(r"([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)", response)
+            for ref in potential_refs:
+                if ref.lower() not in existing_titles and len(ref) > 3:
+                    follow_ups.append(Question(
+                        id=f"ref_{ref.lower().replace(' ', '_')}",
+                        text=f"You mentioned '{ref}'. Is this a process, role, or system we should document?",
+                        question_type=QuestionType.CLOSED,
+                        priority=QuestionPriority.OPTIONAL,
+                        follow_up_for=question_id,
+                    ))
+                    break  # Only ask about one reference at a time
+
+        # Check for step mentions that need elaboration
+        if "step" in response.lower() or any(c.isdigit() for c in response):
+            if len(response) < 100:  # Short response about steps
+                follow_ups.append(Question(
+                    id=f"{question_id}_elaborate_steps",
+                    text="Can you walk me through these steps in more detail?",
+                    question_type=QuestionType.OPEN,
+                    priority=QuestionPriority.RECOMMENDED,
+                    follow_up_for=question_id,
+                ))
+
+        return follow_ups
+
+    def generate_gap_questions(
+        self,
+        gaps: list[str],
+        context: QuestionContext,
+    ) -> list[Question]:
+        """Generate questions to fill identified knowledge gaps."""
+        questions = []
+
+        gap_question_map = {
+            "missing_owner": Question(
+                id="gap_owner",
+                text="Who is responsible for maintaining and updating this?",
+                question_type=QuestionType.OPEN,
+                priority=QuestionPriority.REQUIRED,
+            ),
+            "missing_tools": Question(
+                id="gap_tools",
+                text="What tools or systems are used in this process?",
+                question_type=QuestionType.LIST,
+                priority=QuestionPriority.REQUIRED,
+            ),
+            "missing_timeline": Question(
+                id="gap_timeline",
+                text="How long does this typically take? Are there any SLAs?",
+                question_type=QuestionType.OPEN,
+                priority=QuestionPriority.RECOMMENDED,
+            ),
+            "missing_exceptions": Question(
+                id="gap_exceptions",
+                text="Are there any exceptions or special cases to be aware of?",
+                question_type=QuestionType.OPEN,
+                priority=QuestionPriority.RECOMMENDED,
+            ),
+            "missing_metrics": Question(
+                id="gap_metrics",
+                text="How do you measure success or track performance?",
+                question_type=QuestionType.LIST,
+                priority=QuestionPriority.RECOMMENDED,
+            ),
+        }
+
+        for gap in gaps:
+            if gap in gap_question_map:
+                questions.append(gap_question_map[gap])
+
+        return questions
+
+    async def generate_smart_question(
+        self,
+        context: QuestionContext,
+        previous_qa: list[tuple[str, str]],
+    ) -> Question | None:
+        """
+        Use LLM to generate a contextually relevant follow-up question.
+        Requires llm_callback to be set.
+        """
+        if not self.llm_callback:
+            return None
+
+        # Build prompt for LLM
+        qa_history = "\n".join([f"Q: {q}\nA: {a}" for q, a in previous_qa[-5:]])
+
+        prompt = f"""You are helping document organizational knowledge about: {context.subject}
+Document type: {context.target_node_type.value}
+
+Previous Q&A:
+{qa_history}
+
+Based on this conversation, generate ONE follow-up question that would help complete the documentation.
+The question should:
+1. Fill in gaps in the information provided
+2. Clarify any ambiguous points
+3. Explore important details not yet covered
+
+Return ONLY the question text, nothing else."""
+
+        try:
+            question_text = self.llm_callback("system", prompt)
+            return Question(
+                id=f"smart_{uuid4().hex[:8]}",
+                text=question_text.strip(),
+                question_type=QuestionType.OPEN,
+                priority=QuestionPriority.RECOMMENDED,
+                metadata={"generated": True},
+            )
+        except Exception as e:
+            logger.warning(f"Failed to generate smart question: {e}")
+            return None
+
+    def format_question_for_display(self, question: Question) -> str:
+        """Format a question for user display."""
+        text = question.text
+
+        if question.context:
+            text = f"{text}\n\n(Context: {question.context})"
+
+        if question.examples:
+            examples_str = ", ".join(question.examples[:3])
+            text = f"{text}\n\nExamples: {examples_str}"
+
+        if question.options:
+            options_str = "\n".join([f"  {i+1}. {opt}" for i, opt in enumerate(question.options)])
+            text = f"{text}\n\nOptions:\n{options_str}"
+
+        return text