hyperagents 1.2.3rc5.post3__py3-none-any.whl

civilization/graph/knowledge_linker.py

@@ -0,0 +1,348 @@
+"""
+Knowledge linker for establishing relationships between civilization nodes.
+Supports automatic link detection, relationship inference, and graph traversal.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+import re
+
+from ..schema import (
+    CivilizationNode, NodeType,
+    SOP, Role, Person, Checklist, Runbook, Workflow, JobDescription,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LinkType(str, Enum):
+    # Hierarchical relationships
+    PARENT_OF = "parent_of"
+    CHILD_OF = "child_of"
+
+    # Process relationships
+    PRECEDES = "precedes"
+    FOLLOWS = "follows"
+    TRIGGERS = "triggers"
+    TRIGGERED_BY = "triggered_by"
+
+    # Ownership/responsibility
+    OWNS = "owns"
+    OWNED_BY = "owned_by"
+    RESPONSIBLE_FOR = "responsible_for"
+    ASSIGNED_TO = "assigned_to"
+
+    # Reference relationships
+    REFERENCES = "references"
+    REFERENCED_BY = "referenced_by"
+    RELATED_TO = "related_to"
+
+    # Role relationships
+    REQUIRES_ROLE = "requires_role"
+    REQUIRED_BY_ROLE = "required_by_role"
+    USES_TOOL = "uses_tool"
+
+    # Version relationships
+    VERSION_OF = "version_of"
+    SUPERSEDES = "supersedes"
+    SUPERSEDED_BY = "superseded_by"
+
+
+@dataclass
+class KnowledgeLink:
+    """A link between two civilization nodes."""
+    id: UUID = field(default_factory=uuid4)
+    source_id: UUID = field(default_factory=uuid4)
+    target_id: UUID = field(default_factory=uuid4)
+    link_type: LinkType = LinkType.RELATED_TO
+    strength: float = 1.0  # 0.0-1.0, indicates confidence/relevance
+    auto_detected: bool = False
+    description: str | None = None
+    metadata: dict = field(default_factory=dict)
+
+    def inverse(self) -> "KnowledgeLink":
+        """Get the inverse of this link (swap source and target, flip type)."""
+        inverse_types = {
+            LinkType.PARENT_OF: LinkType.CHILD_OF,
+            LinkType.CHILD_OF: LinkType.PARENT_OF,
+            LinkType.PRECEDES: LinkType.FOLLOWS,
+            LinkType.FOLLOWS: LinkType.PRECEDES,
+            LinkType.TRIGGERS: LinkType.TRIGGERED_BY,
+            LinkType.TRIGGERED_BY: LinkType.TRIGGERS,
+            LinkType.OWNS: LinkType.OWNED_BY,
+            LinkType.OWNED_BY: LinkType.OWNS,
+            LinkType.REFERENCES: LinkType.REFERENCED_BY,
+            LinkType.REFERENCED_BY: LinkType.REFERENCES,
+            LinkType.SUPERSEDES: LinkType.SUPERSEDED_BY,
+            LinkType.SUPERSEDED_BY: LinkType.SUPERSEDES,
+        }
+        return KnowledgeLink(
+            source_id=self.target_id,
+            target_id=self.source_id,
+            link_type=inverse_types.get(self.link_type, self.link_type),
+            strength=self.strength,
+            auto_detected=self.auto_detected,
+            metadata=self.metadata,
+        )
+
+
+class KnowledgeLinker:
+    """
+    Establishes and manages relationships between civilization nodes.
+    Supports automatic link detection and relationship inference.
+    """
+
+    def __init__(self, org_id: str, store=None):
+        self.org_id = org_id
+        self.store = store
+        self._links: list[KnowledgeLink] = []
+        self._link_index: dict[UUID, list[KnowledgeLink]] = {}
+
+    def add_link(self, link: KnowledgeLink) -> KnowledgeLink:
+        """Add a link to the graph."""
+        self._links.append(link)
+        self._link_index.setdefault(link.source_id, []).append(link)
+        self._link_index.setdefault(link.target_id, []).append(link.inverse())
+        return link
+
+    def create_link(
+        self,
+        source_id: UUID,
+        target_id: UUID,
+        link_type: LinkType,
+        strength: float = 1.0,
+        description: str | None = None,
+    ) -> KnowledgeLink:
+        """Create and add a new link."""
+        link = KnowledgeLink(
+            source_id=source_id,
+            target_id=target_id,
+            link_type=link_type,
+            strength=strength,
+            description=description,
+        )
+        return self.add_link(link)
+
+    def get_links_from(self, node_id: UUID) -> list[KnowledgeLink]:
+        """Get all links originating from a node."""
+        return [l for l in self._link_index.get(node_id, []) if l.source_id == node_id]
+
+    def get_links_to(self, node_id: UUID) -> list[KnowledgeLink]:
+        """Get all links pointing to a node."""
+        return [l for l in self._links if l.target_id == node_id]
+
+    def get_all_links(self, node_id: UUID) -> list[KnowledgeLink]:
+        """Get all links involving a node."""
+        return self._link_index.get(node_id, [])
+
+    def get_links_by_type(self, node_id: UUID, link_type: LinkType) -> list[KnowledgeLink]:
+        """Get links of a specific type from a node."""
+        return [l for l in self.get_links_from(node_id) if l.link_type == link_type]
+
+    def detect_links(self, nodes: list[CivilizationNode]) -> list[KnowledgeLink]:
+        """
+        Automatically detect links between nodes based on content analysis.
+        """
+        detected_links: list[KnowledgeLink] = []
+        node_map = {n.id: n for n in nodes}
+
+        # Build lookup tables
+        role_map: dict[str, UUID] = {}
+        sop_map: dict[str, UUID] = {}
+
+        for node in nodes:
+            if isinstance(node, Role):
+                role_map[node.role_title.lower()] = node.id
+            elif isinstance(node, SOP):
+                sop_map[node.title.lower()] = node.id
+
+        # Detect SOP -> Role links
+        for node in nodes:
+            if isinstance(node, SOP):
+                for role_name in node.roles_involved:
+                    role_id = role_map.get(role_name.lower())
+                    if role_id:
+                        link = KnowledgeLink(
+                            source_id=node.id,
+                            target_id=role_id,
+                            link_type=LinkType.REQUIRES_ROLE,
+                            auto_detected=True,
+                            strength=0.9,
+                        )
+                        detected_links.append(link)
+
+        # Detect SOP -> SOP links (related_sops field)
+        for node in nodes:
+            if isinstance(node, SOP):
+                for related_id in node.related_sops:
+                    if related_id in node_map:
+                        link = KnowledgeLink(
+                            source_id=node.id,
+                            target_id=related_id,
+                            link_type=LinkType.RELATED_TO,
+                            auto_detected=True,
+                            strength=0.8,
+                        )
+                        detected_links.append(link)
+
+        # Detect Checklist -> SOP links
+        for node in nodes:
+            if isinstance(node, Checklist) and node.related_sop_id:
+                if node.related_sop_id in node_map:
+                    link = KnowledgeLink(
+                        source_id=node.id,
+                        target_id=node.related_sop_id,
+                        link_type=LinkType.CHILD_OF,
+                        auto_detected=True,
+                        strength=1.0,
+                    )
+                    detected_links.append(link)
+
+        # Detect Person -> Role links
+        for node in nodes:
+            if isinstance(node, Person) and node.role_id:
+                if node.role_id in node_map:
+                    link = KnowledgeLink(
+                        source_id=node.id,
+                        target_id=node.role_id,
+                        link_type=LinkType.ASSIGNED_TO,
+                        auto_detected=True,
+                        strength=1.0,
+                    )
+                    detected_links.append(link)
+
+        # Detect text-based links using title/content matching
+        detected_links.extend(self._detect_text_links(nodes))
+
+        return detected_links
+
+    def _detect_text_links(self, nodes: list[CivilizationNode]) -> list[KnowledgeLink]:
+        """Detect links based on text content analysis."""
+        links = []
+
+        # Build title index
+        title_to_id: dict[str, UUID] = {}
+        for node in nodes:
+            # Normalize title
+            title_key = node.title.lower().strip()
+            title_to_id[title_key] = node.id
+
+        # Look for mentions of other nodes' titles in content
+        for node in nodes:
+            content = self._get_node_content(node)
+            if not content:
+                continue
+
+            for title, target_id in title_to_id.items():
+                if target_id == node.id:
+                    continue
+                # Simple substring matching (could be enhanced with NLP)
+                if title in content.lower() and len(title) > 5:
+                    links.append(KnowledgeLink(
+                        source_id=node.id,
+                        target_id=target_id,
+                        link_type=LinkType.REFERENCES,
+                        auto_detected=True,
+                        strength=0.6,
+                    ))
+
+        return links
+
+    def _get_node_content(self, node: CivilizationNode) -> str:
+        """Extract searchable text content from a node."""
+        parts = [node.title]
+
+        if isinstance(node, SOP):
+            parts.append(node.purpose)
+            parts.append(node.scope)
+            for step in node.steps:
+                parts.append(step.title)
+                parts.append(step.description)
+        elif isinstance(node, Role):
+            parts.extend(node.responsibilities)
+            parts.extend(node.accountabilities)
+        elif isinstance(node, JobDescription):
+            parts.append(node.summary)
+            parts.extend(node.responsibilities)
+
+        return " ".join(filter(None, parts))
+
+    def find_related(
+        self,
+        node_id: UUID,
+        max_depth: int = 2,
+        link_types: list[LinkType] | None = None,
+    ) -> list[tuple[UUID, int, LinkType]]:
+        """
+        Find all related nodes within a certain graph distance.
+        Returns list of (node_id, distance, link_type).
+        """
+        results: list[tuple[UUID, int, LinkType]] = []
+        visited = {node_id}
+        queue: list[tuple[UUID, int]] = [(node_id, 0)]
+
+        while queue:
+            current_id, depth = queue.pop(0)
+            if depth >= max_depth:
+                continue
+
+            for link in self.get_links_from(current_id):
+                if link_types and link.link_type not in link_types:
+                    continue
+                if link.target_id not in visited:
+                    visited.add(link.target_id)
+                    results.append((link.target_id, depth + 1, link.link_type))
+                    queue.append((link.target_id, depth + 1))
+
+        return results
+
+    def compute_importance(self, node_id: UUID) -> float:
+        """
+        Compute a simple importance score based on incoming links.
+        Similar to PageRank but simplified.
+        """
+        incoming = self.get_links_to(node_id)
+        # Weight by link strength
+        return sum(l.strength for l in incoming)
+
+    def get_link_statistics(self) -> dict:
+        """Get statistics about links in the graph."""
+        type_counts: dict[str, int] = {}
+        for link in self._links:
+            type_counts[link.link_type.value] = type_counts.get(link.link_type.value, 0) + 1
+
+        return {
+            "total_links": len(self._links),
+            "auto_detected": sum(1 for l in self._links if l.auto_detected),
+            "manual": sum(1 for l in self._links if not l.auto_detected),
+            "by_type": type_counts,
+            "average_strength": sum(l.strength for l in self._links) / len(self._links) if self._links else 0,
+        }
+
+    def to_dict(self) -> dict:
+        """Export all links to dictionary format."""
+        return {
+            "org_id": self.org_id,
+            "links": [
+                {
+                    "id": str(l.id),
+                    "source_id": str(l.source_id),
+                    "target_id": str(l.target_id),
+                    "link_type": l.link_type.value,
+                    "strength": l.strength,
+                    "auto_detected": l.auto_detected,
+                    "description": l.description,
+                    "metadata": l.metadata,
+                }
+                for l in self._links
+            ],
+        }
+
+    def bulk_add_links(self, links: list[KnowledgeLink]) -> int:
+        """Add multiple links at once. Returns count of links added."""
+        for link in links:
+            self.add_link(link)
+        return len(links)

civilization/graph/org_graph.py

@@ -0,0 +1,348 @@
+"""
+Organizational graph for representing reporting structures, teams, and hierarchies.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Iterator
+from uuid import UUID, uuid4
+
+from ..schema import Person, Role, OrgChart, OrgUnit
+
+logger = logging.getLogger(__name__)
+
+
+class OrgNodeType(str, Enum):
+    PERSON = "person"
+    ROLE = "role"
+    TEAM = "team"
+    DEPARTMENT = "department"
+    DIVISION = "division"
+    ORGANIZATION = "organization"
+
+
+class OrgEdgeType(str, Enum):
+    REPORTS_TO = "reports_to"
+    MANAGES = "manages"
+    MEMBER_OF = "member_of"
+    LEADS = "leads"
+    COLLABORATES_WITH = "collaborates_with"
+    DOTTED_LINE_TO = "dotted_line_to"
+
+
+@dataclass
+class OrgNode:
+    """A node in the organizational graph."""
+    id: UUID
+    node_type: OrgNodeType
+    name: str
+    title: str | None = None
+    department: str | None = None
+    level: int = 0  # Hierarchy level (0 = root)
+    metadata: dict = field(default_factory=dict)
+
+    def __hash__(self):
+        return hash(self.id)
+
+
+@dataclass
+class OrgEdge:
+    """An edge connecting two organizational nodes."""
+    source_id: UUID
+    target_id: UUID
+    edge_type: OrgEdgeType
+    weight: float = 1.0
+    metadata: dict = field(default_factory=dict)
+
+    def __hash__(self):
+        return hash((self.source_id, self.target_id, self.edge_type))
+
+
+class OrgGraph:
+    """
+    Graph representation of organizational structure.
+    Supports hierarchy traversal, team composition queries, and path finding.
+    """
+
+    def __init__(self, org_id: str):
+        self.org_id = org_id
+        self._nodes: dict[UUID, OrgNode] = {}
+        self._edges: list[OrgEdge] = []
+        self._adjacency: dict[UUID, list[OrgEdge]] = {}
+        self._reverse_adjacency: dict[UUID, list[OrgEdge]] = {}
+
+    def add_node(self, node: OrgNode) -> None:
+        """Add a node to the graph."""
+        self._nodes[node.id] = node
+        if node.id not in self._adjacency:
+            self._adjacency[node.id] = []
+        if node.id not in self._reverse_adjacency:
+            self._reverse_adjacency[node.id] = []
+
+    def add_edge(self, edge: OrgEdge) -> None:
+        """Add an edge to the graph."""
+        if edge.source_id not in self._nodes or edge.target_id not in self._nodes:
+            raise ValueError("Both source and target nodes must exist in the graph")
+        self._edges.append(edge)
+        self._adjacency[edge.source_id].append(edge)
+        self._reverse_adjacency[edge.target_id].append(edge)
+
+    def get_node(self, node_id: UUID) -> OrgNode | None:
+        """Get a node by ID."""
+        return self._nodes.get(node_id)
+
+    def get_edges_from(self, node_id: UUID) -> list[OrgEdge]:
+        """Get all edges originating from a node."""
+        return self._adjacency.get(node_id, [])
+
+    def get_edges_to(self, node_id: UUID) -> list[OrgEdge]:
+        """Get all edges pointing to a node."""
+        return self._reverse_adjacency.get(node_id, [])
+
+    def get_manager(self, person_id: UUID) -> OrgNode | None:
+        """Get the manager of a person."""
+        edges = self.get_edges_from(person_id)
+        for edge in edges:
+            if edge.edge_type == OrgEdgeType.REPORTS_TO:
+                return self.get_node(edge.target_id)
+        return None
+
+    def get_direct_reports(self, manager_id: UUID) -> list[OrgNode]:
+        """Get all direct reports of a manager."""
+        edges = self.get_edges_to(manager_id)
+        reports = []
+        for edge in edges:
+            if edge.edge_type == OrgEdgeType.REPORTS_TO:
+                node = self.get_node(edge.source_id)
+                if node:
+                    reports.append(node)
+        return reports
+
+    def get_team_members(self, team_id: UUID) -> list[OrgNode]:
+        """Get all members of a team."""
+        edges = self.get_edges_to(team_id)
+        members = []
+        for edge in edges:
+            if edge.edge_type == OrgEdgeType.MEMBER_OF:
+                node = self.get_node(edge.source_id)
+                if node:
+                    members.append(node)
+        return members
+
+    def get_reporting_chain(self, person_id: UUID) -> list[OrgNode]:
+        """Get the full reporting chain from person to CEO."""
+        chain = []
+        current = self.get_node(person_id)
+        visited = set()
+
+        while current and current.id not in visited:
+            visited.add(current.id)
+            manager = self.get_manager(current.id)
+            if manager:
+                chain.append(manager)
+                current = manager
+            else:
+                break
+
+        return chain
+
+    def get_all_descendants(self, node_id: UUID) -> list[OrgNode]:
+        """Get all descendants (direct and indirect reports) of a node."""
+        descendants = []
+        to_visit = [node_id]
+        visited = set()
+
+        while to_visit:
+            current_id = to_visit.pop(0)
+            if current_id in visited:
+                continue
+            visited.add(current_id)
+
+            direct_reports = self.get_direct_reports(current_id)
+            for report in direct_reports:
+                descendants.append(report)
+                to_visit.append(report.id)
+
+        return descendants
+
+    def find_common_manager(self, person1_id: UUID, person2_id: UUID) -> OrgNode | None:
+        """Find the lowest common manager of two people."""
+        chain1 = set([person1_id] + [n.id for n in self.get_reporting_chain(person1_id)])
+        chain2 = self.get_reporting_chain(person2_id)
+
+        for manager in chain2:
+            if manager.id in chain1:
+                return manager
+
+        # Check if person1 is in person2's chain
+        if person1_id in set(n.id for n in chain2):
+            return self.get_node(person1_id)
+
+        return None
+
+    def calculate_distance(self, node1_id: UUID, node2_id: UUID) -> int | None:
+        """Calculate organizational distance between two nodes (BFS)."""
+        if node1_id == node2_id:
+            return 0
+
+        visited = {node1_id}
+        queue = [(node1_id, 0)]
+
+        while queue:
+            current_id, distance = queue.pop(0)
+
+            # Check all adjacent nodes (both directions)
+            neighbors = []
+            for edge in self.get_edges_from(current_id):
+                neighbors.append(edge.target_id)
+            for edge in self.get_edges_to(current_id):
+                neighbors.append(edge.source_id)
+
+            for neighbor_id in neighbors:
+                if neighbor_id == node2_id:
+                    return distance + 1
+                if neighbor_id not in visited:
+                    visited.add(neighbor_id)
+                    queue.append((neighbor_id, distance + 1))
+
+        return None  # No path found
+
+    def get_department_members(self, department: str) -> list[OrgNode]:
+        """Get all nodes in a department."""
+        return [n for n in self._nodes.values() if n.department == department]
+
+    def get_nodes_by_type(self, node_type: OrgNodeType) -> list[OrgNode]:
+        """Get all nodes of a specific type."""
+        return [n for n in self._nodes.values() if n.node_type == node_type]
+
+    def calculate_span_of_control(self, manager_id: UUID) -> int:
+        """Calculate span of control (number of direct reports)."""
+        return len(self.get_direct_reports(manager_id))
+
+    def calculate_depth(self) -> int:
+        """Calculate maximum depth of the org hierarchy."""
+        max_depth = 0
+        for node in self._nodes.values():
+            chain = self.get_reporting_chain(node.id)
+            max_depth = max(max_depth, len(chain) + 1)
+        return max_depth
+
+    def to_dict(self) -> dict:
+        """Export graph to dictionary format."""
+        return {
+            "org_id": self.org_id,
+            "nodes": [
+                {
+                    "id": str(n.id),
+                    "node_type": n.node_type.value,
+                    "name": n.name,
+                    "title": n.title,
+                    "department": n.department,
+                    "level": n.level,
+                    "metadata": n.metadata,
+                }
+                for n in self._nodes.values()
+            ],
+            "edges": [
+                {
+                    "source_id": str(e.source_id),
+                    "target_id": str(e.target_id),
+                    "edge_type": e.edge_type.value,
+                    "weight": e.weight,
+                    "metadata": e.metadata,
+                }
+                for e in self._edges
+            ],
+        }
+
+    @classmethod
+    def from_org_chart(cls, org_chart: OrgChart) -> "OrgGraph":
+        """Build an OrgGraph from an OrgChart node."""
+        graph = cls(org_id=org_chart.org_id)
+
+        # Add org root
+        org_node = OrgNode(
+            id=org_chart.id,
+            node_type=OrgNodeType.ORGANIZATION,
+            name=org_chart.organization_name,
+            level=0,
+        )
+        graph.add_node(org_node)
+
+        # Process units
+        unit_nodes: dict[str, OrgNode] = {}
+        for unit in org_chart.units:
+            unit_type_map = {
+                "division": OrgNodeType.DIVISION,
+                "department": OrgNodeType.DEPARTMENT,
+                "team": OrgNodeType.TEAM,
+            }
+            unit_node = OrgNode(
+                id=uuid4(),
+                node_type=unit_type_map.get(unit.unit_type, OrgNodeType.TEAM),
+                name=unit.name,
+                metadata={"unit_id": unit.unit_id, "mission": unit.mission},
+            )
+            graph.add_node(unit_node)
+            unit_nodes[unit.unit_id] = unit_node
+
+        # Add hierarchy edges
+        for unit in org_chart.units:
+            unit_node = unit_nodes[unit.unit_id]
+            if unit.parent_unit_id:
+                parent = unit_nodes.get(unit.parent_unit_id)
+                if parent:
+                    graph.add_edge(OrgEdge(
+                        source_id=unit_node.id,
+                        target_id=parent.id,
+                        edge_type=OrgEdgeType.MEMBER_OF,
+                    ))
+            else:
+                # Top-level unit reports to org
+                graph.add_edge(OrgEdge(
+                    source_id=unit_node.id,
+                    target_id=org_chart.id,
+                    edge_type=OrgEdgeType.MEMBER_OF,
+                ))
+
+        return graph
+
+    @classmethod
+    def from_people(cls, org_id: str, people: list[Person]) -> "OrgGraph":
+        """Build an OrgGraph from a list of Person nodes."""
+        graph = cls(org_id=org_id)
+
+        # Add all people as nodes
+        for person in people:
+            node = OrgNode(
+                id=person.id,
+                node_type=OrgNodeType.PERSON,
+                name=person.name,
+                title=person.department,
+                department=person.department,
+                metadata={
+                    "email": person.email,
+                    "location": person.location,
+                    "timezone": person.timezone,
+                },
+            )
+            graph.add_node(node)
+
+        # Add reporting relationships
+        person_map = {p.id: p for p in people}
+        for person in people:
+            if person.manager_id and person.manager_id in person_map:
+                graph.add_edge(OrgEdge(
+                    source_id=person.id,
+                    target_id=person.manager_id,
+                    edge_type=OrgEdgeType.REPORTS_TO,
+                ))
+
+        return graph
+
+    def __len__(self) -> int:
+        return len(self._nodes)
+
+    def __iter__(self) -> Iterator[OrgNode]:
+        return iter(self._nodes.values())