raise-core 2.2.1__tar.gz

raise_core-2.2.1/.gitignore

@@ -0,0 +1,111 @@
+# IDE / editor directories
+.specstory/
+.cursor/
+.idea/
+.vscode/
+
+# Claude Code local settings (user-specific)
+.claude/settings.local.json
+CLAUDE.local.md
+.claude/worktrees/
+.claude/projects/
+
+# Claude Code legacy files (superseded, prevent re-addition)
+.claude/RAI.md
+.claude/RAI-naming.md
+.claude/rai.archive/
+
+# RaiSE generated/cache files
+.raise/cache/
+.raise/confluence-pages.yaml
+
+# RaiSE derived artifacts (rebuild with `rai memory build`)
+.raise/rai/memory/index.json
+
+# RaiSE personal directory (per-developer, not shared)
+.raise/rai/personal/
+
+# RaiSE sync state (per-instance JIRA mappings, not shared)
+.raise/rai/sync/
+
+# Temporary files
+*.tmp
+*.bak-*
+*.log
+.DS_Store
+Thumbs.db
+
+# Script generated folders (if testing locally)
+.specify-raise/commands/
+
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+.rai/memory/graph.json
+.envrc
+
+# Legacy telemetry (should be in personal/, will migrate)
+.raise/rai/telemetry/
+
+# MCP server config (contains API tokens)
+.mcp.json
+
+# Secrets & credentials
+.env
+.env.*
+*.pem
+*.key
+.pypirc
+credentials.json
+*.sqlite
+.netrc
+.raise/mcp/
+!.raise/mcp/catalog.yaml
+
+# Website (Astro)
+site/node_modules/
+site/dist/
+site/.astro/
+site/.wrangler/

raise_core-2.2.1/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: raise-core
+Version: 2.2.1
+Summary: RaiSE Core - Shared domain models for the RaiSE framework
+Author-email: Emilio Osorio <emilio@humansys.ai>
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: pydantic>=2.6.0

raise_core-2.2.1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "raise-core"
+version = "2.2.1"
+description = "RaiSE Core - Shared domain models for the RaiSE framework"
+authors = [
+    {name = "Emilio Osorio", email = "emilio@humansys.ai"}
+]
+license = {text = "Apache-2.0"}
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.6.0",
+    "networkx>=3.6.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/raise_core"]

raise_core-2.2.1/src/raise_core/__init__.py

@@ -0,0 +1,12 @@
+"""RaiSE Core - Shared domain models for the RaiSE framework.
+
+rai-core is the shared domain contract between COMMUNITY (rai-cli) and PRO (rai-server).
+It contains the vocabulary, protocols, and logic that any RaiSE component needs.
+
+Domain axes:
+- graph: Models, engine, query, scoring, backends (E275)
+- workflow: Work item types, state machines, gates (future)
+- governance: Extensible artifact type schema (future)
+"""
+
+__version__ = "2.2.1"

raise_core-2.2.1/src/raise_core/governance/__init__.py

@@ -0,0 +1,7 @@
+"""Governance domain — extensible artifact type schema.
+
+Placeholder for future implementation. Will contain:
+- Extensible artifact type registry (beyond fixed CoreArtifactType)
+- Governance vocabulary shared across CLI, server, and integrations
+- Schema versioning and migration support
+"""

raise_core-2.2.1/src/raise_core/graph/__init__.py

@@ -0,0 +1,6 @@
+"""Graph domain — models, engine, query, and backends.
+
+The ontological backbone of RaiSE. All knowledge (patterns, governance,
+discovery, sessions) converges here as typed nodes and edges in a
+queryable graph.
+"""

raise_core-2.2.1/src/raise_core/graph/backends/__init__.py

@@ -0,0 +1 @@
+"""Graph backend implementations — storage abstraction for the knowledge graph."""

raise_core-2.2.1/src/raise_core/graph/backends/filesystem.py

@@ -0,0 +1,83 @@
+"""Filesystem-based graph backend.
+
+Built-in COMMUNITY backend — persists the knowledge graph to local JSON files.
+Zero external dependencies beyond NetworkX (already a core dependency).
+
+Architecture: ADR-036 (KnowledgeGraphBackend)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import networkx as nx  # type: ignore[import-untyped]
+
+from raise_core.graph.backends.models import BackendHealth
+from raise_core.graph.engine import Graph
+
+__all__ = ["FilesystemGraphBackend", "get_active_backend"]
+
+
+class FilesystemGraphBackend:
+    """Built-in graph backend — persists to local filesystem.
+
+    COMMUNITY backend. Zero external dependencies.
+    Registered as entry point 'local' in rai.graph.backends.
+
+    Args:
+        path: Path to the graph JSON file (e.g. `.raise/rai/memory/index.json`).
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def persist(self, graph: Graph) -> None:
+        """Save graph to JSON file using NetworkX node_link_data format.
+
+        Args:
+            graph: The graph to persist.
+        """
+        data: dict[str, Any] = nx.node_link_data(graph.graph)  # type: ignore[assignment]
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(data, indent=2, default=str), encoding="utf-8")
+
+    def load(self) -> Graph:
+        """Load graph from the configured path.
+
+        Returns:
+            Graph instance with loaded data.
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist.
+            json.JSONDecodeError: If the file is not valid JSON.
+        """
+        loaded_data: dict[str, Any] = json.loads(
+            self.path.read_text(encoding="utf-8")
+        )
+        instance = Graph()
+        instance.graph = nx.node_link_graph(
+            loaded_data, directed=True, multigraph=True
+        )
+        return instance
+
+    def health(self) -> BackendHealth:
+        """Check backend health. Filesystem is always available."""
+        return BackendHealth(
+            status="healthy",
+            message="Filesystem backend operational",
+            metadata={"backend": "filesystem"},
+        )
+
+
+def get_active_backend(path: Path) -> FilesystemGraphBackend:
+    """Resolve the active graph backend for the given path.
+
+    Returns FilesystemGraphBackend (COMMUNITY). Future: tier-based
+    selection via env vars (DualWriteBackend when RAI_SERVER_URL set).
+
+    Args:
+        path: Path to the graph JSON file.
+    """
+    return FilesystemGraphBackend(path=path)

raise_core-2.2.1/src/raise_core/graph/backends/models.py

@@ -0,0 +1,22 @@
+"""Pydantic models for graph backend boundaries.
+
+Architecture: ADR-036 (KnowledgeGraphBackend)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BackendHealth(BaseModel):
+    """Health check result for a graph backend."""
+
+    status: str = Field(
+        ..., description="'healthy', 'degraded', or 'unavailable'"
+    )
+    message: str = Field(default="", description="Human-readable status detail")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Backend-specific diagnostics"
+    )

raise_core-2.2.1/src/raise_core/graph/backends/protocol.py

@@ -0,0 +1,27 @@
+"""Protocol contract for graph backend implementations.
+
+Architecture: ADR-036 (Graph Backend)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from raise_core.graph.backends.models import BackendHealth
+
+if TYPE_CHECKING:
+    from raise_core.graph.engine import Graph
+
+
+@runtime_checkable
+class KnowledgeGraphBackend(Protocol):
+    """ADR-036: Graph storage abstraction.
+
+    Implementations: FilesystemGraphBackend (built-in), ApiGraphBackend (PRO).
+    """
+
+    def persist(self, graph: Graph) -> None: ...
+
+    def load(self) -> Graph: ...
+
+    def health(self) -> BackendHealth: ...

raise_core-2.2.1/src/raise_core/graph/engine.py

@@ -0,0 +1,236 @@
+"""Knowledge graph engine.
+
+Wraps NetworkX MultiDiGraph for storing and querying cross-domain concepts.
+This is a pure in-memory graph; persistence is handled by
+KnowledgeGraphBackend implementations (ADR-036).
+
+Architecture: ADR-019 Unified Context Graph Architecture
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from typing import Any
+
+import networkx as nx  # type: ignore[import-untyped]
+
+from raise_core.graph.models import (
+    EdgeType,
+    GraphEdge,
+    GraphNode,
+    NodeType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Graph:
+    """NetworkX-based knowledge graph.
+
+    Wraps a NetworkX MultiDiGraph to provide typed operations for adding,
+    retrieving, and persisting concepts and relationships.
+
+    Attributes:
+        graph: The underlying NetworkX MultiDiGraph.
+
+    Examples:
+        >>> g = Graph()
+        >>> node = GraphNode(
+        ...     id="PAT-001",
+        ...     type="pattern",
+        ...     content="Test pattern",
+        ...     created="2026-02-03"
+        ... )
+        >>> g.add_concept(node)
+        >>> g.node_count
+        1
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty graph."""
+        self.graph: nx.MultiDiGraph[str] = nx.MultiDiGraph()
+
+    def _reconstruct_node(self, node_id: str, data: dict[str, Any]) -> GraphNode:
+        """Reconstruct a typed GraphNode from serialized dict."""
+        data["id"] = node_id
+        node_type = data.get("type", "")
+        cls = GraphNode.registered_types().get(node_type)
+        if cls:
+            return cls.model_validate(data)
+        if node_type:
+            logger.warning(
+                "Node type '%s' not registered (missing plugin?). "
+                "Run 'rai memory build' to regenerate graph.",
+                node_type,
+            )
+        return GraphNode.model_validate(data)
+
+    def add_concept(self, node: GraphNode) -> None:
+        """Add a concept node to the graph.
+
+        Args:
+            node: The concept node to add.
+        """
+        self.graph.add_node(node.id, **node.model_dump())
+
+    def add_relationship(self, edge: GraphEdge) -> None:
+        """Add a relationship edge to the graph.
+
+        Args:
+            edge: The concept edge to add.
+        """
+        self.graph.add_edge(
+            edge.source,
+            edge.target,
+            type=edge.type,
+            weight=edge.weight,
+            **edge.metadata,
+        )
+
+    def get_concept(self, concept_id: str) -> GraphNode | None:
+        """Get a concept by ID.
+
+        Args:
+            concept_id: The unique concept identifier.
+
+        Returns:
+            The GraphNode if found, None otherwise.
+        """
+        if concept_id not in self.graph.nodes:
+            return None
+        data = dict(self.graph.nodes[concept_id])
+        return self._reconstruct_node(concept_id, data)
+
+    def get_concepts_by_type(self, node_type: NodeType) -> list[GraphNode]:
+        """Get all concepts of a specific type.
+
+        Args:
+            node_type: The node type to filter by.
+
+        Returns:
+            List of GraphNode instances matching the type.
+        """
+        concepts: list[GraphNode] = []
+        node_id: str
+        for node_id in self.graph.nodes:
+            data: dict[str, Any] = dict(self.graph.nodes[node_id])
+            if data.get("type") == node_type:
+                concepts.append(self._reconstruct_node(node_id, data))
+        return concepts
+
+    def get_neighbors(
+        self,
+        concept_id: str,
+        depth: int = 1,
+        edge_types: list[EdgeType] | None = None,
+    ) -> list[GraphNode]:
+        """Get neighboring concepts via BFS traversal.
+
+        Args:
+            concept_id: Starting concept ID.
+            depth: Maximum traversal depth (default 1).
+            edge_types: Optional filter for edge types.
+
+        Returns:
+            List of neighboring GraphNode instances.
+        """
+        if concept_id not in self.graph.nodes:
+            return []
+
+        visited: set[str] = {concept_id}
+        current_level: set[str] = {concept_id}
+        neighbors: list[GraphNode] = []
+
+        for _ in range(depth):
+            next_level: set[str] = set()
+            for nid in current_level:
+                # Get outgoing edges
+                out_edge: tuple[str, str, dict[str, Any]]
+                for out_edge in self.graph.out_edges(nid, data=True):
+                    target: str = out_edge[1]
+                    edge_data: dict[str, Any] = out_edge[2]
+                    edge_matches = (
+                        edge_types is None or edge_data.get("type") in edge_types
+                    )
+                    if edge_matches and target not in visited:
+                        visited.add(target)
+                        next_level.add(target)
+                # Get incoming edges
+                in_edge: tuple[str, str, dict[str, Any]]
+                for in_edge in self.graph.in_edges(nid, data=True):
+                    source: str = in_edge[0]
+                    edge_data = in_edge[2]
+                    edge_matches = (
+                        edge_types is None or edge_data.get("type") in edge_types
+                    )
+                    if edge_matches and source not in visited:
+                        visited.add(source)
+                        next_level.add(source)
+            current_level = next_level
+
+        # Convert to GraphNode instances
+        node_id: str
+        for node_id in visited:
+            if node_id != concept_id:
+                concept = self.get_concept(node_id)
+                if concept:
+                    neighbors.append(concept)
+
+        return neighbors
+
+    def iter_concepts(self) -> Iterator[GraphNode]:
+        """Iterate over all concepts in the graph.
+
+        Skips nodes that fail deserialization (e.g. schema drift from a removed
+        plugin) and emits a warning instead of crashing. See RAISE-136.
+
+        Yields:
+            GraphNode instances for each node.
+        """
+        node_id: str
+        for node_id in self.graph.nodes:
+            data: dict[str, Any] = dict(self.graph.nodes[node_id])
+            try:
+                yield self._reconstruct_node(node_id, data)
+            except Exception as e:
+                logger.warning(
+                    "Skipping node '%s' (type=%s): %s",
+                    node_id,
+                    data.get("type", "unknown"),
+                    e,
+                )
+
+    def iter_relationships(self) -> Iterator[GraphEdge]:
+        """Iterate over all relationships in the graph.
+
+        Yields:
+            GraphEdge instances for each edge.
+        """
+        edge_tuple: tuple[str, str, dict[str, Any]]
+        for edge_tuple in self.graph.edges(data=True):
+            source: str = edge_tuple[0]
+            target: str = edge_tuple[1]
+            data: dict[str, Any] = edge_tuple[2]
+            edge_type: str = data.get("type", "related_to")
+            weight: float = float(data.get("weight", 1.0))
+            metadata: dict[str, Any] = {
+                k: v for k, v in data.items() if k not in ("type", "weight")
+            }
+            yield GraphEdge(
+                source=source,
+                target=target,
+                type=edge_type,
+                weight=weight,
+                metadata=metadata,
+            )
+
+    @property
+    def node_count(self) -> int:
+        """Get the number of nodes in the graph."""
+        return self.graph.number_of_nodes()
+
+    @property
+    def edge_count(self) -> int:
+        """Get the number of edges in the graph."""
+        return self.graph.number_of_edges()

raise_core-2.2.1/src/raise_core/graph/models.py

@@ -0,0 +1,208 @@
+"""Pydantic models for the knowledge graph.
+
+Core data structures: nodes, edges, type systems. All knowledge in RaiSE
+(patterns, governance, discovery, sessions) is represented as typed nodes
+and directed edges in a queryable graph.
+
+Architecture: ADR-019 Unified Context Graph Architecture
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, Field, model_validator
+
+# --- Node type system (open for plugins) ---
+NodeType = str
+
+
+class GraphNode(BaseModel):
+    """Base class for all knowledge graph nodes. Auto-registers subclasses.
+
+    Pattern: pytest Node + Airflow BaseOperator + Kedro AbstractDataset.
+    Subclasses define node_type and optionally add typed fields.
+
+    Examples:
+        >>> class JiraSprintNode(GraphNode, node_type="jira.sprint"):
+        ...     sprint_id: str = ""
+        >>> node = JiraSprintNode(id="S1", content="Sprint 1", created="2026-01-01")
+        >>> node.type
+        'jira.sprint'
+    """
+
+    _registry: ClassVar[dict[str, type[GraphNode]]] = {}
+
+    id: str = Field(..., description="Unique identifier (e.g., 'PAT-001', '§2')")
+    type: str = Field(default="", description="Node type (auto-set by subclass)")
+    content: str = Field(..., description="Main text content or description")
+    source_file: str | None = Field(default=None, description="Path to source file")
+    created: str = Field(..., description="ISO timestamp when created")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Type-specific attributes"
+    )
+
+    def __init_subclass__(cls, node_type: str | None = None, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if node_type is not None:
+            cls.__node_type__ = node_type  # type: ignore[attr-defined]
+            GraphNode._registry[node_type] = cls
+
+    @model_validator(mode="before")
+    @classmethod
+    def _set_default_type(cls, data: dict[str, Any]) -> dict[str, Any]:
+        """Auto-set type field from subclass registration."""
+        if hasattr(cls, "__node_type__"):
+            node_type: str = cls.__node_type__  # type: ignore[attr-defined]
+            data.setdefault("type", node_type)
+        return data
+
+    @classmethod
+    def resolve(cls, node_type: str) -> type[GraphNode]:
+        """Resolve a node_type string to its registered class."""
+        return cls._registry[node_type]
+
+    @classmethod
+    def registered_types(cls) -> dict[str, type[GraphNode]]:
+        """All registered node type mappings."""
+        return dict(cls._registry)
+
+    @property
+    def token_estimate(self) -> int:
+        """Estimate tokens for this concept.
+
+        Returns:
+            Estimated token count (content length // 4).
+        """
+        return len(self.content) // 4
+
+
+# --- Core node types (18) — documented extension points ---
+
+
+class PatternNode(GraphNode, node_type="pattern"):
+    """Learned patterns from memory. Extension: confidence scores, decay metadata."""
+
+
+class CalibrationNode(GraphNode, node_type="calibration"):
+    """Velocity/estimation data. Extension: per-team calibration fields."""
+
+
+class SessionNode(GraphNode, node_type="session"):
+    """Session history records. Extension: agent-specific session data."""
+
+
+class PrincipleNode(GraphNode, node_type="principle"):
+    """Constitution principles. Extension: org-level principle overrides."""
+
+
+class RequirementNode(GraphNode, node_type="requirement"):
+    """PRD requirements. Extension: priority, stakeholder fields."""
+
+
+class OutcomeNode(GraphNode, node_type="outcome"):
+    """Vision outcomes. Extension: OKR linkage fields."""
+
+
+class ProjectNode(GraphNode, node_type="project"):
+    """Project definitions. Extension: multi-repo project metadata."""
+
+
+class EpicNode(GraphNode, node_type="epic"):
+    """Epic scopes. Extension: Jira epic fields (key, board, sprint)."""
+
+
+class StoryNode(GraphNode, node_type="story"):
+    """Story work items. Extension: PM tool fields (assignee, status)."""
+
+
+class SkillNode(GraphNode, node_type="skill"):
+    """Skill metadata. Extension: registry, versioning, ownership."""
+
+
+class DecisionNode(GraphNode, node_type="decision"):
+    """Architecture decisions. Extension: review status, superseded-by."""
+
+
+class GuardrailNode(GraphNode, node_type="guardrail"):
+    """Code standards. Extension: enforcement level, exceptions."""
+
+
+class TermNode(GraphNode, node_type="term"):
+    """Glossary definitions. Extension: translations, domain scope."""
+
+
+class ComponentNode(GraphNode, node_type="component"):
+    """Discovered code components. Extension: language-specific metadata."""
+
+
+class ModuleNode(GraphNode, node_type="module"):
+    """Architecture module knowledge. Extension: dependency metrics."""
+
+
+class ArchitectureNode(GraphNode, node_type="architecture"):
+    """Architecture docs. Extension: diagram links, review dates."""
+
+
+class BoundedContextNode(GraphNode, node_type="bounded_context"):
+    """DDD bounded contexts. Extension: team ownership, API surface."""
+
+
+class LayerNode(GraphNode, node_type="layer"):
+    """Architectural layers. Extension: deployment mapping."""
+
+
+class ReleaseNode(GraphNode, node_type="release"):
+    """Release milestones. Extension: changelog, artifact URLs."""
+
+
+class ArtifactNode(GraphNode, node_type="artifact"):
+    """Work artifacts (scope, design, plan docs). Extension: versioning, approval status."""
+
+
+# --- Edge type system (open for plugins, flat — no hierarchy needed) ---
+EdgeType = str
+
+
+class CoreEdgeTypes:
+    """Constants for the 11 core edge types."""
+
+    LEARNED_FROM = "learned_from"
+    GOVERNED_BY = "governed_by"
+    APPLIES_TO = "applies_to"
+    NEEDS_CONTEXT = "needs_context"
+    IMPLEMENTS = "implements"
+    PART_OF = "part_of"
+    RELATED_TO = "related_to"
+    DEPENDS_ON = "depends_on"
+    BELONGS_TO = "belongs_to"
+    IN_LAYER = "in_layer"
+    CONSTRAINED_BY = "constrained_by"
+
+
+class GraphEdge(BaseModel):
+    """An edge in the knowledge graph. Open type system.
+
+    Represents a directed relationship between two concepts.
+
+    Examples:
+        >>> edge = GraphEdge(
+        ...     source="PAT-001",
+        ...     target="SES-015",
+        ...     type="learned_from",
+        ...     weight=1.0,
+        ...     metadata={"confidence": 0.9}
+        ... )
+        >>> edge.source
+        'PAT-001'
+        >>> edge.type
+        'learned_from'
+    """
+
+    source: str = Field(..., description="Source node ID")
+    target: str = Field(..., description="Target node ID")
+    type: EdgeType = Field(..., description="Relationship type")
+    weight: float = Field(default=1.0, description="Edge weight for ranking")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional relationship attributes"
+    )

raise_core-2.2.1/src/raise_core/graph/query.py

@@ -0,0 +1,496 @@
+"""Knowledge graph query engine.
+
+Provides query capabilities for the knowledge graph, enabling skills to
+retrieve relevant patterns, calibration data, governance principles,
+and work items.
+
+Architecture: ADR-019 Unified Context Graph Architecture
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import date
+from enum import StrEnum
+from math import exp, log, sqrt
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from raise_core.graph.engine import Graph
+from raise_core.graph.models import EdgeType, GraphNode, NodeType
+
+# --- Scoring constants ---
+SCORING_HALF_LIFE_DAYS: int = 30
+SCORING_W_RECENCY: float = 0.3
+SCORING_W_RELEVANCE: float = 0.7
+SCORING_WILSON_Z: float = 1.96
+SCORING_LOW_WILSON_THRESHOLD: float = 0.15
+
+
+class QueryStrategy(StrEnum):
+    """Query strategy for context retrieval.
+
+    Attributes:
+        KEYWORD_SEARCH: Match keywords in node content, return top N by relevance.
+        CONCEPT_LOOKUP: Direct concept ID lookup with optional BFS neighbors.
+    """
+
+    KEYWORD_SEARCH = "keyword_search"
+    CONCEPT_LOOKUP = "concept_lookup"
+
+
+class Query(BaseModel):
+    """Query parameters for context retrieval.
+
+    Attributes:
+        query: Query string (keywords or concept ID).
+        strategy: Query execution strategy.
+        max_depth: Maximum BFS traversal depth (0-5).
+        types: Optional filter for node types.
+        limit: Maximum number of results.
+
+    Examples:
+        >>> query = Query(query="planning estimation")
+        >>> query = Query(
+        ...     query="PAT-001",
+        ...     strategy=QueryStrategy.CONCEPT_LOOKUP,
+        ...     max_depth=2,
+        ... )
+    """
+
+    query: str = Field(..., description="Query string (keywords or concept ID)")
+    strategy: QueryStrategy = Field(
+        default=QueryStrategy.KEYWORD_SEARCH,
+        description="Query execution strategy",
+    )
+    max_depth: int = Field(
+        default=1,
+        ge=0,
+        le=5,
+        description="Maximum BFS traversal depth",
+    )
+    types: list[NodeType] | None = Field(
+        default=None,
+        description="Filter by node types",
+    )
+    edge_types: list[EdgeType] | None = Field(
+        default=None,
+        description="Filter by edge types (concept_lookup only)",
+    )
+    limit: int = Field(
+        default=10,
+        ge=1,
+        le=50,
+        description="Maximum number of results",
+    )
+
+
+class ArchitecturalContext(BaseModel):
+    """Full architectural context for a module.
+
+    Combines domain (bounded context), layer, constraints (guardrails),
+    and dependencies into a single structured result.
+    """
+
+    module: GraphNode
+    domain: GraphNode | None = None
+    layer: GraphNode | None = None
+    constraints: list[GraphNode] = Field(default_factory=lambda: [])
+    dependencies: list[GraphNode] = Field(default_factory=lambda: [])
+
+
+class QueryMetadata(BaseModel):
+    """Metadata about query result.
+
+    Attributes:
+        query: Original query string.
+        strategy: Strategy used for execution.
+        total_concepts: Number of concepts in result.
+        total_available: Total matching concepts before limit applied.
+        token_estimate: Estimated token count for result.
+        execution_time_ms: Query execution time in milliseconds.
+        types_found: Count of concepts by type.
+    """
+
+    query: str = Field(..., description="Original query string")
+    strategy: QueryStrategy = Field(..., description="Strategy used")
+    total_concepts: int = Field(..., description="Number of concepts returned")
+    total_available: int = Field(
+        0, description="Total matching concepts before limit applied"
+    )
+    token_estimate: int = Field(..., description="Estimated token count")
+    execution_time_ms: float = Field(..., description="Execution time in ms")
+    types_found: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count of concepts by type",
+    )
+
+
+class QueryResult(BaseModel):
+    """Result of context query.
+
+    Attributes:
+        concepts: Concepts matching the query.
+        metadata: Query result metadata.
+    """
+
+    concepts: list[GraphNode] = Field(
+        default_factory=lambda: [],
+        description="Concepts matching the query",
+    )
+    metadata: QueryMetadata = Field(..., description="Query metadata")
+
+    def to_json(self) -> str:
+        """Serialize result to JSON."""
+        return self.model_dump_json(indent=2)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> QueryResult:
+        """Deserialize result from JSON."""
+        return cls.model_validate_json(json_str)
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count for text.
+
+    Uses heuristic: character count // 4 (roughly 4 chars per token).
+    """
+    return len(text) // 4
+
+
+def wilson_lower_bound(
+    positives: int,
+    negatives: int,
+    z: float = SCORING_WILSON_Z,
+) -> float:
+    """Compute Wilson score lower bound for binary ratings.
+
+    Proven at Reddit/Yelp/Amazon scale. Conservative with small sample sizes —
+    the correct approach for patterns with few evaluations.
+
+    Args:
+        positives: Number of positive evaluations.
+        negatives: Number of negative evaluations.
+        z: Z-score for confidence level (default: 1.96 = 95%).
+
+    Returns:
+        Wilson lower bound in [0, 1].
+
+    Raises:
+        ValueError: If total observations is 0.
+    """
+    n = positives + negatives
+    if n == 0:
+        raise ValueError("Cannot compute Wilson lower bound with 0 observations")
+    p_hat = positives / n
+    z2 = z * z
+    numerator = (
+        p_hat + z2 / (2 * n) - z * sqrt((p_hat * (1 - p_hat) + z2 / (4 * n)) / n)
+    )
+    denominator = 1 + z2 / n
+    return numerator / denominator
+
+
+def calculate_relevance_score(
+    content: str,
+    keywords: list[str],
+    created: str,
+    metadata: dict[str, Any] | None = None,
+) -> float:
+    """Calculate composite relevance score for a concept.
+
+    Foundational patterns (foundational=True or base=True) are exempt from
+    temporal decay and score on keyword relevance only. All other patterns use:
+        score = (w_r * recency + w_k * keyword_relevance) * wilson_modifier
+
+    Where recency uses half-life exponential decay (H=30d) and wilson_modifier
+    is the Wilson score lower bound of positive evaluations.
+    """
+    if metadata is None:
+        metadata = {}
+
+    content_lower = content.lower()
+
+    # Normalized keyword relevance
+    if keywords:
+        hits = sum(1 for kw in keywords if kw.lower() in content_lower)
+        relevance = hits / len(keywords)
+    else:
+        relevance = 0.0
+
+    # Foundational patterns: exempt from decay — check both field names (PAT-E-153)
+    if metadata.get("foundational") or metadata.get("base"):
+        return round(relevance, 4)
+
+    # Recency: half-life exponential decay
+    try:
+        created_date = date.fromisoformat(created[:10])
+        age_days = max(0, (date.today() - created_date).days)
+    except (ValueError, IndexError):
+        age_days = 0
+    recency = exp(-log(2) / SCORING_HALF_LIFE_DAYS * age_days)
+
+    base = SCORING_W_RECENCY * recency + SCORING_W_RELEVANCE * relevance
+
+    # Wilson validation modifier
+    evaluations = metadata.get("evaluations") or 0
+    if not evaluations:
+        return round(base, 4)
+
+    positives = metadata.get("positives") or 0
+    negatives = metadata.get("negatives") or 0
+    if positives + negatives == 0:
+        return round(base, 4)  # defensive guard for data inconsistency
+
+    modifier = wilson_lower_bound(positives, negatives)
+    return round(base * modifier, 4)
+
+
+class QueryEngine:
+    """Query engine for the knowledge graph.
+
+    Provides keyword search and concept lookup capabilities for
+    retrieving relevant context from the graph.
+
+    Attributes:
+        graph: The knowledge graph to query.
+
+    Examples:
+        >>> engine = QueryEngine(graph)
+        >>> result = engine.query(Query(query="planning estimation"))
+        >>> print(f"Found {len(result.concepts)} concepts")
+    """
+
+    def __init__(self, graph: Graph) -> None:
+        """Initialize query engine with graph.
+
+        Args:
+            graph: Knowledge graph to query.
+        """
+        self.graph = graph
+
+    def query(self, query: Query) -> QueryResult:
+        """Execute query and return results."""
+        start_time = time.time()
+
+        # Execute strategy
+        if query.strategy == QueryStrategy.KEYWORD_SEARCH:
+            concepts, total_available = self._keyword_search(query)
+        else:  # CONCEPT_LOOKUP
+            concepts, total_available = self._concept_lookup(query)
+
+        execution_time_ms = (time.time() - start_time) * 1000
+
+        # Calculate metadata
+        metadata = self._calculate_metadata(
+            query, concepts, execution_time_ms, total_available
+        )
+
+        return QueryResult(concepts=concepts, metadata=metadata)
+
+    def _keyword_search(
+        self, query: Query
+    ) -> tuple[list[GraphNode], int]:
+        """Execute keyword search strategy.
+
+        Matches keywords against node content, returns top N by relevance.
+
+        Args:
+            query: Query parameters.
+
+        Returns:
+            Tuple of (matching concepts sorted by relevance, total matches before limit).
+        """
+        keywords = query.query.lower().split()
+        if not keywords:
+            return [], 0
+
+        scored_concepts: list[tuple[float, GraphNode]] = []
+
+        for concept in self.graph.iter_concepts():
+            # Apply type filter
+            if query.types and concept.type not in query.types:
+                continue
+
+            # Check if any keyword matches (include node type in searchable text)
+            searchable = f"{concept.type} {concept.content}".lower()
+            if not any(kw in searchable for kw in keywords):
+                continue
+
+            # Calculate relevance score
+            score = calculate_relevance_score(
+                concept.content,
+                keywords,
+                concept.created,
+                concept.metadata,
+            )
+            scored_concepts.append((score, concept))
+
+        # Sort by score descending
+        scored_concepts.sort(key=lambda x: x[0], reverse=True)
+
+        total_available = len(scored_concepts)
+
+        # Apply limit
+        limited = [concept for _, concept in scored_concepts[: query.limit]]
+        return limited, total_available
+
+    def _concept_lookup(
+        self, query: Query
+    ) -> tuple[list[GraphNode], int]:
+        """Execute concept lookup strategy.
+
+        Direct ID lookup with optional BFS neighbor traversal.
+
+        Args:
+            query: Query parameters.
+
+        Returns:
+            Tuple of (concepts list, total matches before limit).
+        """
+        concept_id = query.query
+
+        # Direct lookup
+        concept = self.graph.get_concept(concept_id)
+        if concept is None:
+            return [], 0
+
+        # Apply type filter to main concept
+        if query.types and concept.type not in query.types:
+            concepts: list[GraphNode] = []
+        else:
+            concepts = [concept]
+
+        # Get neighbors if depth > 0
+        if query.max_depth > 0:
+            neighbors = self.graph.get_neighbors(
+                concept_id, depth=query.max_depth, edge_types=query.edge_types
+            )
+            for neighbor in neighbors:
+                if query.types and neighbor.type not in query.types:
+                    continue
+                if neighbor.id not in [c.id for c in concepts]:
+                    concepts.append(neighbor)
+
+        total_available = len(concepts)
+
+        # Apply limit
+        return concepts[: query.limit], total_available
+
+    def _calculate_metadata(
+        self,
+        query: Query,
+        concepts: list[GraphNode],
+        execution_time_ms: float,
+        total_available: int,
+    ) -> QueryMetadata:
+        """Calculate metadata for query result."""
+        total_text = " ".join(c.content for c in concepts)
+        token_estimate = estimate_tokens(total_text)
+
+        types_found: dict[str, int] = {}
+        for concept in concepts:
+            node_type = concept.type
+            types_found[node_type] = types_found.get(node_type, 0) + 1
+
+        return QueryMetadata(
+            query=query.query,
+            strategy=query.strategy,
+            total_concepts=len(concepts),
+            total_available=total_available,
+            token_estimate=token_estimate,
+            execution_time_ms=execution_time_ms,
+            types_found=types_found,
+        )
+
+    # =========================================================================
+    # Architectural Context Helpers
+    # =========================================================================
+
+    def find_domain_for(self, module_id: str) -> GraphNode | None:
+        """Find the bounded context a module belongs to."""
+        neighbors = self.graph.get_neighbors(
+            module_id, depth=1, edge_types=["belongs_to"]
+        )
+        for node in neighbors:
+            if node.type == "bounded_context":
+                return node
+        return None
+
+    def find_layer_for(self, module_id: str) -> GraphNode | None:
+        """Find the architectural layer a module belongs to."""
+        neighbors = self.graph.get_neighbors(
+            module_id, depth=1, edge_types=["in_layer"]
+        )
+        for node in neighbors:
+            if node.type == "layer":
+                return node
+        return None
+
+    def find_constraints_for(self, module_id: str) -> list[GraphNode]:
+        """Find all guardrails that constrain a module."""
+        domain = self.find_domain_for(module_id)
+        if domain is None:
+            return []
+
+        neighbors = self.graph.get_neighbors(
+            domain.id, depth=1, edge_types=["constrained_by"]
+        )
+        return [n for n in neighbors if n.type == "guardrail"]
+
+    def find_release_for(self, epic_id: str) -> GraphNode | None:
+        """Find the release an epic belongs to.
+
+        Follows outgoing ``part_of`` edge from the epic node to find
+        a release node.
+
+        Args:
+            epic_id: Epic node ID (e.g., ``"epic-e19"``).
+
+        Returns:
+            The release node, or None if not found.
+        """
+        neighbors = self.graph.get_neighbors(
+            epic_id, depth=1, edge_types=["part_of"]
+        )
+        for node in neighbors:
+            if node.type == "release":
+                return node
+        return None
+
+    def get_architectural_context(
+        self, module_id: str
+    ) -> ArchitecturalContext | None:
+        """Get full architectural context for a module.
+
+        Combines domain, layer, constraints, and dependencies into a
+        single structured result.
+
+        Args:
+            module_id: Module node ID (e.g., ``"mod-memory"``).
+
+        Returns:
+            ArchitecturalContext with all available information,
+            or None if module doesn't exist.
+        """
+        module = self.graph.get_concept(module_id)
+        if module is None:
+            return None
+
+        domain = self.find_domain_for(module_id)
+        layer = self.find_layer_for(module_id)
+        constraints = self.find_constraints_for(module_id)
+
+        dep_neighbors = self.graph.get_neighbors(
+            module_id, depth=1, edge_types=["depends_on"]
+        )
+        dependencies = [n for n in dep_neighbors if n.type == "module"]
+
+        return ArchitecturalContext(
+            module=module,
+            domain=domain,
+            layer=layer,
+            constraints=constraints,
+            dependencies=dependencies,
+        )

raise_core-2.2.1/src/raise_core/workflow/__init__.py

@@ -0,0 +1,9 @@
+"""Workflow domain — work item types, state machines, and gates.
+
+Placeholder for future implementation. Will contain:
+- WorkItemType definitions (Epic, Story, Task)
+- State machine definitions per work item type
+- Gate protocol and default gate implementations
+- Default RaiSE workflow (out of the box)
+- Per-org/repo workflow override mechanism
+"""