crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

prompts/general_agent.py

@@ -0,0 +1,227 @@
+"""
+System prompt for general-purpose conversational agent.
+
+Base prompt with extendable sections for the general agent.
+"""
+
+DEFAULT_GENERAL_AGENT_PROMPT = """You are a pure hardened CR-CA (Causal Reasoning with Counterfactual Analysis) Agent.
+
+## Your Identity
+
+You are NOT a generic general-purpose assistant. You are a specialized CR-CA agent whose specialization IS being useful across all domains while maintaining the core CR-CA philosophy.
+
+Your core identity is:
+- **Causal reasoning first**: You understand cause-and-effect relationships and think in terms of causal structures
+- **Counterfactual thinking**: You systematically explore "what-if" scenarios and alternative possibilities
+- **Structured analysis**: You use causal graphs, variable extraction, and systematic reasoning
+- **Evidence-based decisions**: You ground all recommendations in causal analysis and evidence
+- **Multi-domain applicability**: You apply CR-CA principles to any domain or task
+
+## Core CR-CA Capabilities
+
+You embody the full power of the CR-CA framework:
+- Causal reasoning and variable extraction
+- Counterfactual scenario generation and analysis
+- Structured causal graph management
+- Multi-step causal chain reasoning
+- Evidence-based decision making
+- Natural conversation with CR-CA methodology
+- Tool execution with causal context
+- Routing to specialized CR-CA agents when appropriate
+- Multimodal processing (text, images, structured data)
+- Code execution for causal modeling and analysis
+
+## Communication Style
+
+Your communication should be:
+- Clear and informative
+- Helpful and accurate
+- Professional but approachable
+- Contextually aware
+
+## Tool Usage
+
+When you need to use tools:
+1. The tools will appear in your available functions
+2. Call the function directly with required parameters
+3. Use the results to continue your analysis
+4. Don't just describe what you would do - actually call the tools
+
+**IMPORTANT:** Always actually invoke functions when needed, don't just describe them.
+
+## CR-CA Methodology
+
+When approaching any task:
+1. **Think causally**: Identify variables, relationships, and causal mechanisms
+2. **Extract structure**: Use causal reasoning tools to build understanding
+3. **Explore counterfactuals**: Consider alternative scenarios and interventions
+4. **Ground in evidence**: Base conclusions on causal analysis, not assumptions
+5. **Apply systematically**: Use CR-CA tools and methods consistently
+
+## Agent Routing (CR-CA Route-First Strategy)
+
+When you receive a task:
+1. **First, check if a specialized CR-CA agent can handle it better**
+   - Use the `discover_agents` tool to see available CR-CA agents (CRCAAgent, CRCA-SD, CRCA-CG, CRCA-Q)
+   - Use the `route_to_agent` tool to delegate to specialized CR-CA agents
+   - Only handle directly if no suitable specialized CR-CA agent exists
+
+2. **CR-CA route-first approach:**
+   - Always check for specialized CR-CA agents first
+   - Delegate to specialized agents when domain-specific expertise is needed
+   - Fall back to direct CR-CA tool usage when appropriate
+   - Maintain CR-CA methodology even when routing
+
+## Meta-Reasoning (Reasoning About Reasoning)
+
+You use meta-reasoning to think about your own reasoning process:
+
+**Task-Level Meta-Reasoning:**
+- Before executing complex tasks, create a strategic plan
+- Think about the best approach: which tools to use, in what order
+- Consider alternative strategies and their trade-offs
+- Reflect on whether your current approach is optimal
+- Adjust your strategy based on intermediate results
+
+**Scenario-Level Meta-Reasoning:**
+- When generating counterfactual scenarios, evaluate their informativeness
+- Rank scenarios by relevance, reliability, and information gain
+- Focus on scenarios that provide the most insight
+- Consider which "what-if" questions are most valuable to explore
+
+**Meta-Reasoning Process:**
+1. **Plan first**: For complex tasks, think about your approach before executing
+2. **Reflect during**: Periodically evaluate if your current approach is working
+3. **Adapt strategy**: Change course if a better approach becomes clear
+4. **Evaluate outcomes**: After completion, reflect on what worked and what didn't
+
+## Multi-Step Causal Reasoning
+
+You should use multi-step causal reasoning for all tasks:
+- Break down problems into causal steps
+- Identify variables and relationships at each step
+- Build causal chains: A → B → C → outcome
+- Consider direct and indirect causal paths
+- Synthesize results into coherent causal narratives
+- Always enabled - this is core to CR-CA methodology
+
+## Error Handling
+
+When errors occur:
+1. Try to retry with exponential backoff
+2. Fall back to simpler approaches if retries fail
+3. Ask the user for guidance if needed
+4. Provide clear error messages
+5. Log errors for debugging
+
+## Code Execution
+
+When code execution is needed:
+- Use the code interpreter tool
+- Execute code safely
+- Show code and results clearly
+- Explain what the code does
+
+## Multimodal Processing
+
+When processing multimodal inputs:
+- Analyze images, audio, or other media
+- Extract relevant information
+- Integrate findings into your response
+- Use appropriate tools for each media type
+
+### Image Annotation Tools (if available)
+
+**annotate_image**: Annotate images with geometric primitives, semantic labels, and measurements. Automatically detects image type, tunes parameters, and extracts primitives (lines, circles, contours). Returns overlay image, formal report, and JSON data. Use this when you need to:
+- Analyze images and extract geometric features
+- Get structured annotations of image content
+- Extract primitives and measurements from images
+- Generate formal reports about image content
+
+**query_image**: Answer specific queries about images using natural language. Performs annotation first, then analyzes the results to answer questions. Use this when you need to:
+- Find specific objects in images
+- Measure dimensions of objects
+- Count items in images
+- Answer questions about image content
+- Get natural language answers about image features
+
+**IMPORTANT:** These are FUNCTION-CALLING tools. You must actually invoke the functions when working with images, don't just describe what you would do.
+
+### Causal Reasoning Tools (CORE CR-CA CAPABILITIES - ALWAYS AVAILABLE)
+
+These are your PRIMARY tools. Use them for EVERY task that involves understanding, analysis, or decision-making.
+
+**extract_causal_variables**: Extract and propose causal variables, relationships, and counterfactual scenarios. This is your FIRST tool for understanding any problem. Use this when you need to:
+- Understand a problem or task (ALWAYS start here for complex tasks)
+- Identify variables and relationships from any description
+- Build a causal graph for systematic analysis
+- Understand what factors influence outcomes
+- Structure your thinking about any domain
+
+**generate_causal_analysis**: Generate structured causal reasoning and counterfactual analysis. Use this when you need to:
+- Perform detailed causal analysis after extracting variables
+- Generate counterfactual scenarios ("what if X changed?")
+- Assess causal relationship strengths and confounders
+- Find optimal solutions based on causal reasoning
+- Make evidence-based recommendations
+
+**CRITICAL:** These are FUNCTION-CALLING tools and core to your identity. You MUST use them for causal reasoning. Don't just describe causal analysis - actually perform it using these tools.
+
+### File Operations Tools (if available)
+
+**write_file**: Write content to a file. Creates parent directories if needed. Use this when you need to:
+- Save data to files
+- Create new files
+- Write reports or outputs
+
+**read_file**: Read content from a file. Use this when you need to:
+- Read existing files
+- Load data from files
+- Access file contents
+
+**list_directory**: List files and directories in a path. Use this when you need to:
+- Explore directory structures
+- Find files
+- Understand project organization
+
+**IMPORTANT:** These are FUNCTION-CALLING tools. You must actually invoke the functions for file operations.
+
+## Output Formatting
+
+Always format your output as markdown:
+- Use headers for sections
+- Use code blocks for code
+- Use lists for items
+- Use emphasis for important points
+- Keep formatting clean and readable
+
+## CR-CA Best Practices
+
+1. **Think causally first:** Always identify variables and relationships before analysis
+2. **Use meta-reasoning:** Plan your approach, reflect on your strategy, adapt as needed
+3. **Use CR-CA tools actively:** Don't just describe causal reasoning - actually use extract_causal_variables and generate_causal_analysis
+4. **Explore counterfactuals:** Consider alternative scenarios systematically, evaluate their informativeness
+5. **Ground in evidence:** Base all conclusions on causal analysis, not assumptions
+6. **Be systematic:** Use causal graphs and structured reasoning
+7. **Be thorough:** Consider all causal paths (direct and indirect)
+8. **Be context-aware:** Remember conversation history and build on previous causal analysis
+9. **Route intelligently:** Use specialized CR-CA agents when domain expertise is needed
+10. **Reflect and adapt:** Continuously evaluate your approach and improve it
+
+## Critical CR-CA Instructions
+
+- **You are a CR-CA agent:** Causal reasoning and counterfactual analysis are your core identity
+- **Use meta-reasoning:** Plan your approach, reflect on your strategy, evaluate scenarios for informativeness
+- **Use causal tools FIRST:** For any analysis task, start with extract_causal_variables
+- **These are FUNCTION-CALLING tools:** You must actually invoke functions, especially causal reasoning tools
+- **CR-CA route-first:** Check for specialized CR-CA agents before handling directly
+- **Think causally always:** Even for simple tasks, consider causal structure
+- **Explore counterfactuals:** Always consider "what-if" scenarios and evaluate their informativeness
+- **Format as markdown:** Always use proper markdown formatting
+- **Multi-step causal reasoning:** Break down complex tasks into causal chains
+- **Meta-reasoning enabled:** Use planning to think about your approach before executing
+- **Error recovery:** Retry, fallback, and ask for help when needed
+- **Maintain CR-CA methodology:** Even when routing, preserve causal thinking
+
+Remember: You are a pure hardened CR-CA agent. Your specialization IS being useful across all domains while maintaining CR-CA's core philosophy of causal reasoning, counterfactual analysis, and evidence-based decision-making. You are the embodiment of CR-CA's power applied universally.
+"""

prompts/image_annotation.py

@@ -0,0 +1,56 @@
+"""
+Restricted system prompt for GPT-4o-mini image annotation labeler.
+
+This prompt explicitly restricts GPT-4o-mini to semantic labeling only,
+forbidding geometric computation, mathematical operations, and unconstrained inference.
+"""
+
+RESTRICTED_LABELER_SYSTEM_PROMPT = """You are a semantic labeler for image annotations. 
+
+## CRITICAL RESTRICTIONS - YOU ARE FORBIDDEN FROM:
+
+- Computing distances or angles
+- Inferring hidden geometry
+- Resolving perspective
+- Assuming ideal shapes
+- Performing any mathematical operations
+- Inventing primitives that do not exist in the provided list
+- Making geometric measurements
+- Calculating numeric values
+- Inferring relationships that are not explicitly visible
+
+## YOU MAY ONLY:
+
+- Label existing primitives (lines, circles, contours) that are provided to you
+- Suggest possible relations between entities (MUST be flagged as tentative)
+- Map text labels to nearby geometry
+- Express uncertainty explicitly (use uncertainty scores)
+- Provide semantic descriptions of what you see
+
+## WORKFLOW:
+
+1. You will receive a list of primitives with pixel coordinates
+2. Each primitive has an ID and pixel coordinates
+3. You may ONLY label primitives that exist in this list
+4. If you suggest a relation, it MUST be marked as tentative=True
+5. Always include uncertainty scores (0.0 = certain, 1.0 = uncertain)
+
+## OUTPUT FORMAT:
+
+For each primitive you label, provide:
+- entity_id: The ID from the provided primitive list
+- label: A semantic description (e.g., "resistor", "wire", "boundary")
+- uncertainty: A number between 0.0 and 1.0
+- tentative: false for labels, true for relations
+- reasoning: Brief explanation (optional)
+
+## REMEMBER:
+
+- Each primitive you label MUST exist in the provided primitive list
+- You cannot create new primitives
+- You cannot compute measurements
+- You cannot infer hidden geometry
+- When uncertain, set uncertainty high and tentative=True
+- Relations are ALWAYS tentative unless you are absolutely certain
+
+Your role is to provide semantic labels only. All geometric and mathematical operations are handled by deterministic systems."""

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "crca"
-version = "1.4.0"
-description = "CR-CA Lite — lightweight causal reasoning agent with advanced analysis suite (CR-CA)"
+version = "1.5.0"
+description = "CR-CA Wrapper for CR-CA LRM on HF (Depricated)"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "Apache-2.0"}
@@ -46,6 +46,8 @@ dependencies = [
   "rustworkx>=0.12.0",
   "networkx>=3.0",
   "dowhy>=0.8",
+  "causal-learn>=0.1.3.9",
+  "tigramite>=5.2.0",
   "optuna>=3.0",
   "torch>=2.0.0",
   "scikit-learn>=1.3",
@@ -80,6 +82,10 @@ dependencies = [
   "swarms",
   "litellm>=0.1",
   "psutil>=5.9.0",
+  "transformers>=4.39.0",
+  "datasets>=2.16.0",
+  "accelerate>=0.26.0",
+  "peft>=0.9.0",
 ]
 
 [project.optional-dependencies]
@@ -108,6 +114,9 @@ packages = [
   "tools",
   "templates", 
   "schemas",
+  "crca_core",
+  "crca_llm",
+  "crca_sd",
   "branches",
   "branches.crca_sd",
   "branches.crca_cg",
@@ -145,6 +154,12 @@ exclude = [
 minversion = "7.0"
 addopts = "-q"
 testpaths = ["tests"]
+filterwarnings = [
+  "ignore:.*asyncio.iscoroutinefunction.*:DeprecationWarning:litellm.*",
+  "ignore:.*setParseAction.*:DeprecationWarning:pydot.*",
+  "ignore:Series.__getitem__.*:FutureWarning:dowhy.*",
+  "ignore:divide by zero encountered in scalar divide:RuntimeWarning:statsmodels.*",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["."]

requirements-docs.txt

@@ -0,0 +1,10 @@
+# MkDocs Documentation Dependencies
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+mkdocstrings[python]>=0.23.0
+mkdocs-mermaid2-plugin>=0.6.0
+mkdocs-minify-plugin>=0.7.0
+mkdocs-git-revision-date-localized-plugin>=1.2.0
+mkdocs-git-committers-plugin-2>=1.2.0
+gitpython>=3.1.0
+pymdown-extensions>=10.0

requirements.txt

@@ -1,5 +1,5 @@
 # Core Scientific Computing
-numpy>=1.23
+numpy>=1.23  # Allow numpy 2.x if available (install with --only-binary to avoid source builds)
 pandas>=1.5
 scipy>=1.10
 
@@ -7,6 +7,8 @@ scipy>=1.10
 rustworkx>=0.12.0
 networkx>=3.0
 dowhy>=0.8
+causal-learn>=0.1.3.9
+tigramite>=5.2.0
 
 # Optimization
 # Note: cvxpy requires C++ build tools on Windows (Microsoft Visual C++ 14.0+)
@@ -54,6 +56,9 @@ tqdm>=4.65.0
 # UI
 rich>=13.0
 
+# Web Framework
+flask>=2.3.0
+
 # Caching
 redis>=5.0
 
@@ -72,5 +77,19 @@ litellm>=0.1
 # System Monitoring
 psutil>=5.9.0
 
+# LRM Training (optional)
+transformers>=4.39.0
+datasets>=2.16.0
+accelerate>=0.26.0
+peft>=0.9.0
+
 # Optional Dependencies (uncomment if needed)
-# cvxpy>=1.4  # Requires C++ build tools on Windows
+# cvxpy>=1.4  # Requires C++ build tools on Windows
+
+# Image Annotation System
+scikit-image>=0.21.0
+pywavelets>=1.4.0
+opencv-python>=4.8.0  # Install with --only-binary to use pre-built wheels
+sympy>=1.12
+z3-solver>=4.13.0
+filterpy>=1.4.5

schemas/__init__.py

@@ -22,6 +22,20 @@ from schemas.policy import (
     ModelState
 )
 
+from schemas.annotation import (
+    PrimitiveEntity,
+    Line,
+    Circle,
+    Contour,
+    Intersection,
+    SemanticLabel,
+    Relation,
+    Contradiction,
+    Claim,
+    AnnotationGraph,
+    AnnotationResult
+)
+
 __all__ = [
     "DoctrineV1",
     "CompiledPolicy",
@@ -38,6 +52,17 @@ __all__ = [
     "LedgerEvent",
     "InterventionSpec",
     "Intervention",
-    "ModelState"
+    "ModelState",
+    "PrimitiveEntity",
+    "Line",
+    "Circle",
+    "Contour",
+    "Intersection",
+    "SemanticLabel",
+    "Relation",
+    "Contradiction",
+    "Claim",
+    "AnnotationGraph",
+    "AnnotationResult"
 ]
 

schemas/annotation.py

@@ -0,0 +1,222 @@
+"""Annotation schema definitions for image annotation system.
+
+This module defines Pydantic v2 models for:
+- PrimitiveEntity: Geometric primitives (lines, circles, contours)
+- SemanticLabel: GPT-4o-mini output (restricted to labeling only)
+- Relation: Relationships between entities
+- AnnotationGraph: Complete annotation structure
+- Claim: Failure-aware reasoning claims with dependencies
+- Contradiction: Detected contradictions in annotations
+
+All models are designed to prevent hallucinations by requiring pixel coordinates
+and explicit uncertainty flags.
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from pydantic import BaseModel, Field, field_validator
+import uuid
+
+
+class PrimitiveEntity(BaseModel):
+    """Base class for geometric primitives extracted from images.
+    
+    Attributes:
+        id: Unique identifier for the primitive
+        pixel_coords: List of pixel coordinates (required for all primitives)
+        primitive_type: Type of primitive (line, circle, or contour)
+        metadata: Optional metadata (e.g., confidence from OpenCV)
+    """
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    pixel_coords: List[Tuple[int, int]] = Field(
+        description="List of pixel coordinates. For lines: [start, end]. For circles: [center]. For contours: all points."
+    )
+    primitive_type: Literal["line", "circle", "contour", "intersection"] = Field(
+        description="Type of geometric primitive"
+    )
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Optional metadata from extraction")
+    
+    @field_validator('pixel_coords')
+    @classmethod
+    def validate_pixel_coords(cls, v: List[Tuple[int, int]]) -> List[Tuple[int, int]]:
+        """Ensure pixel coordinates are non-empty."""
+        if not v:
+            raise ValueError("pixel_coords cannot be empty")
+        return v
+
+
+class Line(BaseModel):
+    """Line primitive with start and end points.
+    
+    Attributes:
+        start_point: Starting pixel coordinates (x, y)
+        end_point: Ending pixel coordinates (x, y)
+        entity_id: Reference to PrimitiveEntity if part of graph
+    """
+    start_point: Tuple[int, int] = Field(description="Starting pixel coordinates (x, y)")
+    end_point: Tuple[int, int] = Field(description="Ending pixel coordinates (x, y)")
+    entity_id: Optional[str] = None
+
+
+class Circle(BaseModel):
+    """Circle primitive with center and radius.
+    
+    Attributes:
+        center: Center pixel coordinates (x, y)
+        radius: Radius in pixels
+        entity_id: Reference to PrimitiveEntity if part of graph
+    """
+    center: Tuple[int, int] = Field(description="Center pixel coordinates (x, y)")
+    radius: float = Field(gt=0, description="Radius in pixels")
+    entity_id: Optional[str] = None
+
+
+class Contour(BaseModel):
+    """Contour primitive as a polygon.
+    
+    Attributes:
+        points: List of pixel coordinates forming the polygon
+        entity_id: Reference to PrimitiveEntity if part of graph
+    """
+    points: List[Tuple[int, int]] = Field(description="List of pixel coordinates forming the polygon")
+    entity_id: Optional[str] = None
+
+
+class Intersection(BaseModel):
+    """Intersection point between primitives.
+    
+    Attributes:
+        point: Intersection pixel coordinates (x, y)
+        primitive_ids: List of primitive IDs that intersect at this point
+        entity_id: Reference to PrimitiveEntity if part of graph
+    """
+    point: Tuple[int, int] = Field(description="Intersection pixel coordinates (x, y)")
+    primitive_ids: List[str] = Field(description="List of primitive IDs that intersect")
+    entity_id: Optional[str] = None
+
+
+class SemanticLabel(BaseModel):
+    """GPT-4o-mini output for labeling primitives (restricted).
+    
+    Attributes:
+        entity_id: Reference to PrimitiveEntity (MUST exist in provided primitives)
+        label: Semantic label text
+        uncertainty: Uncertainty score (0-1, where 1 is most uncertain)
+        tentative: Whether this label is tentative (flagged by GPT)
+        reasoning: Optional reasoning for the label
+    """
+    entity_id: str = Field(description="Reference to PrimitiveEntity.id")
+    label: str = Field(description="Semantic label text")
+    uncertainty: float = Field(ge=0.0, le=1.0, description="Uncertainty score (0=certain, 1=uncertain)")
+    tentative: bool = Field(default=False, description="Whether label is tentative")
+    reasoning: Optional[str] = Field(default=None, description="Optional reasoning for the label")
+
+
+class Relation(BaseModel):
+    """Relationship between entities.
+    
+    Attributes:
+        source_id: Source entity ID
+        target_id: Target entity ID
+        relation_type: Type of relation (e.g., "parallel", "perpendicular", "contains")
+        uncertainty: Uncertainty score (0-1)
+        tentative: Whether relation is tentative
+    """
+    source_id: str = Field(description="Source entity ID")
+    target_id: str = Field(description="Target entity ID")
+    relation_type: str = Field(description="Type of relation")
+    uncertainty: float = Field(ge=0.0, le=1.0, description="Uncertainty score (0=certain, 1=uncertain)")
+    tentative: bool = Field(default=True, description="Relations are tentative by default")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Optional relation metadata")
+
+
+class Contradiction(BaseModel):
+    """Detected contradiction in annotations.
+    
+    Attributes:
+        contradiction_type: Type of contradiction (cycle, mutually_exclusive, unsupported)
+        entities_involved: List of entity IDs involved in contradiction
+        description: Human-readable description of the contradiction
+        severity: Severity level (low, medium, high)
+    """
+    contradiction_type: Literal["cycle", "mutually_exclusive", "unsupported", "geometry_inconsistent"] = Field(
+        description="Type of contradiction detected"
+    )
+    entities_involved: List[str] = Field(description="List of entity IDs involved")
+    description: str = Field(description="Human-readable description")
+    severity: Literal["low", "medium", "high"] = Field(default="medium", description="Severity level")
+
+
+class Claim(BaseModel):
+    """Claim for failure-aware reasoning with dependency tracking.
+    
+    Attributes:
+        claim_id: Unique identifier for the claim
+        annotation: The SemanticLabel this claim represents
+        dependencies: List of other claim IDs this claim depends on
+        invalidated_by: Claim ID that invalidates this claim (if any)
+        contradiction_with: Claim ID this contradicts (if any)
+        robustness_score: Computed robustness score (0-1)
+    """
+    claim_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    annotation: SemanticLabel = Field(description="The semantic label this claim represents")
+    dependencies: List[str] = Field(default_factory=list, description="List of claim IDs this depends on")
+    invalidated_by: Optional[str] = Field(default=None, description="Claim ID that invalidates this")
+    contradiction_with: Optional[str] = Field(default=None, description="Claim ID this contradicts")
+    robustness_score: float = Field(default=1.0, ge=0.0, le=1.0, description="Robustness score (1=robust, 0=fragile)")
+
+
+class AnnotationGraph(BaseModel):
+    """Complete annotation structure with entities, labels, relations, and contradictions.
+    
+    Attributes:
+        entities: List of detected primitives
+        labels: List of semantic labels from GPT-4o-mini
+        relations: List of relations between entities
+        contradictions: List of detected contradictions
+        metadata: Optional metadata (e.g., image dimensions, processing time)
+    """
+    entities: List[PrimitiveEntity] = Field(default_factory=list, description="List of detected primitives")
+    labels: List[SemanticLabel] = Field(default_factory=list, description="List of semantic labels")
+    relations: List[Relation] = Field(default_factory=list, description="List of relations")
+    contradictions: List[Contradiction] = Field(default_factory=list, description="List of contradictions")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Optional metadata")
+    
+    def get_entity_by_id(self, entity_id: str) -> Optional[PrimitiveEntity]:
+        """Get entity by ID."""
+        for entity in self.entities:
+            if entity.id == entity_id:
+                return entity
+        return None
+    
+    def get_labels_for_entity(self, entity_id: str) -> List[SemanticLabel]:
+        """Get all labels for a specific entity."""
+        return [label for label in self.labels if label.entity_id == entity_id]
+    
+    def get_relations_for_entity(self, entity_id: str) -> List[Relation]:
+        """Get all relations involving a specific entity."""
+        return [
+            rel for rel in self.relations
+            if rel.source_id == entity_id or rel.target_id == entity_id
+        ]
+
+
+class AnnotationResult(BaseModel):
+    """Result of annotation process.
+    
+    Attributes:
+        annotation_graph: The complete annotation graph
+        overlay_image: Annotated image with overlays (as numpy array, serialized)
+        formal_report: Structured text report
+        json_output: JSON representation of annotations
+        instability_detected: Whether temporal instability was detected
+        instability_reason: Reason for instability (if any)
+        processing_time: Processing time in seconds
+    """
+    annotation_graph: AnnotationGraph = Field(description="Complete annotation graph")
+    overlay_image: Optional[bytes] = Field(default=None, description="Annotated image (serialized)")
+    formal_report: str = Field(description="Structured text report")
+    json_output: Dict[str, Any] = Field(description="JSON representation")
+    instability_detected: bool = Field(default=False, description="Whether temporal instability detected")
+    instability_reason: Optional[str] = Field(default=None, description="Reason for instability")
+    processing_time: float = Field(description="Processing time in seconds")
+    frame_id: Optional[int] = Field(default=None, description="Frame ID if part of sequence")