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

CRCA.py

@@ -72,6 +72,20 @@ except ImportError:
     # Fallback if prompt file doesn't exist
     DEFAULT_CRCA_SYSTEM_PROMPT = None
 
+# Image annotation imports (optional - graceful fallback if not available)
+try:
+    from image_annotation.annotation_engine import ImageAnnotationEngine
+    IMAGE_ANNOTATION_AVAILABLE = True
+except ImportError:
+    IMAGE_ANNOTATION_AVAILABLE = False
+    logger.debug("Image annotation engine not available")
+except Exception as e:
+    IMAGE_ANNOTATION_AVAILABLE = False
+    logger.warning(f"Image annotation engine import failed: {e}")
+
+# Global singleton for image annotation engine (lazy-loaded)
+_image_annotation_engine: Optional[Any] = None
+
 # Policy engine imports (optional - only if policy_mode is enabled)
 try:
     from schemas.policy import DoctrineV1
@@ -771,9 +785,20 @@ class CRCAAgent(Agent):
             **kwargs: Additional arguments passed to parent Agent class
         """
         
+        env_model = os.getenv("CRCA_MOE_MODEL") or os.getenv("CRCA_LLM_MODEL")
+        if env_model and model_name == "gpt-4o":
+            model_name = env_model
+
         cr_ca_schema = CRCAAgent._get_cr_ca_schema()
         extract_variables_schema = CRCAAgent._get_extract_variables_schema()
         
+        # Get image annotation schemas if available
+        image_annotation_schema = None
+        image_query_schema = None
+        if IMAGE_ANNOTATION_AVAILABLE:
+            image_annotation_schema = CRCAAgent._get_image_annotation_schema()
+            image_query_schema = CRCAAgent._get_image_query_schema()
+        
         # Backwards-compatible alias for description
         agent_description = description or agent_description
 
@@ -788,15 +813,18 @@ class CRCAAgent(Agent):
         # Merge tools_list_dictionary from kwargs with CRCA schema
         # Only add CRCA schema if user hasn't explicitly disabled it
         use_crca_tools = kwargs.pop("use_crca_tools", True)  # Default to True for backwards compatibility
+        use_image_annotation = kwargs.pop("use_image_annotation", True)  # Default to True if available
         existing_tools = kwargs.pop("tools_list_dictionary", [])
         if not isinstance(existing_tools, list):
             existing_tools = [existing_tools] if existing_tools else []
         
-        # Only add CRCA schemas if enabled
+        # Build tools list
+        tools_list = []
         if use_crca_tools:
-            tools_list = [cr_ca_schema, extract_variables_schema] + existing_tools
-        else:
-            tools_list = existing_tools
+            tools_list.extend([cr_ca_schema, extract_variables_schema])
+        if use_image_annotation and IMAGE_ANNOTATION_AVAILABLE and image_annotation_schema and image_query_schema:
+            tools_list.extend([image_annotation_schema, image_query_schema])
+        tools_list.extend(existing_tools)
         
         # Get existing callable tools (functions) from kwargs
         existing_callable_tools = kwargs.pop("tools", [])
@@ -844,6 +872,9 @@ class CRCAAgent(Agent):
         super().__init__(**agent_kwargs)
         
         # Now that self exists, create and add the CRCA tool handlers if tools are enabled
+        # Store use_image_annotation for later use
+        self._use_image_annotation = use_image_annotation if IMAGE_ANNOTATION_AVAILABLE else False
+        
         if use_crca_tools:
             # Create a wrapper function with the correct name that matches the schema
             def generate_causal_analysis(
@@ -886,17 +917,77 @@ class CRCAAgent(Agent):
             self.add_tool(generate_causal_analysis)
             self.add_tool(extract_causal_variables)
             
+            # Add image annotation tools if available
+            if self._use_image_annotation and IMAGE_ANNOTATION_AVAILABLE:
+                def annotate_image(
+                    image_path: str,
+                    output_format: str = "all",
+                    frame_id: Optional[int] = None
+                ) -> Dict[str, Any]:
+                    """Tool handler for annotate_image."""
+                    engine = CRCAAgent._get_image_annotation_engine()
+                    if engine is None:
+                        return {"error": "Image annotation engine not available"}
+                    try:
+                        result = engine.annotate(image_path, frame_id=frame_id, output=output_format)
+                        if output_format == "overlay":
+                            return {"overlay_image": "numpy array returned", "shape": str(result.shape) if hasattr(result, 'shape') else "unknown"}
+                        elif output_format == "json":
+                            return result
+                        elif output_format == "report":
+                            return {"report": result}
+                        else:  # all
+                            return {
+                                "entities": len(result.annotation_graph.entities),
+                                "labels": len(result.annotation_graph.labels),
+                                "contradictions": len(result.annotation_graph.contradictions),
+                                "processing_time": result.processing_time,
+                                "formal_report": result.formal_report[:500] + "..." if len(result.formal_report) > 500 else result.formal_report,
+                                "json_summary": {k: str(v)[:200] for k, v in list(result.json_output.items())[:5]}
+                            }
+                    except Exception as e:
+                        logger.error(f"Error in annotate_image tool: {e}")
+                        return {"error": str(e)}
+                
+                def query_image(
+                    image_path: str,
+                    query: str,
+                    frame_id: Optional[int] = None
+                ) -> Dict[str, Any]:
+                    """Tool handler for query_image."""
+                    engine = CRCAAgent._get_image_annotation_engine()
+                    if engine is None:
+                        return {"error": "Image annotation engine not available"}
+                    try:
+                        result = engine.query(image_path, query, frame_id=frame_id)
+                        return {
+                            "answer": result["answer"],
+                            "entities_found": len(result["entities"]),
+                            "measurements": result["measurements"],
+                            "confidence": result["confidence"],
+                            "reasoning": result["reasoning"][:500] + "..." if len(result["reasoning"]) > 500 else result["reasoning"]
+                        }
+                    except Exception as e:
+                        logger.error(f"Error in query_image tool: {e}")
+                        return {"error": str(e)}
+                
+                self.add_tool(annotate_image)
+                self.add_tool(query_image)
+            
             # CRITICAL: Re-initialize tool_struct after adding tools
             # This ensures the BaseTool instance has the updated tools and function_map
             if hasattr(self, 'setup_tools'):
                 self.tool_struct = self.setup_tools()
             
             # Ensure tools_list_dictionary is set with our manual schemas
+            our_tool_names = {"generate_causal_analysis", "extract_causal_variables"}
+            if self._use_image_annotation and IMAGE_ANNOTATION_AVAILABLE:
+                our_tool_names.update({"annotate_image", "query_image"})
+            
             if not self.tools_list_dictionary or len(self.tools_list_dictionary) == 0:
-                self.tools_list_dictionary = [cr_ca_schema, extract_variables_schema] + existing_tools
+                self.tools_list_dictionary = tools_list
             else:
                 # Replace any auto-generated schemas with our manual ones
-                our_tool_names = {"generate_causal_analysis", "extract_causal_variables"}
                 filtered = []
                 for schema in self.tools_list_dictionary:
                     if isinstance(schema, dict):
@@ -905,7 +996,7 @@ class CRCAAgent(Agent):
                             continue  # Skip auto-generated, we'll add manual
                     filtered.append(schema)
                 # Add our manual schemas first, then existing tools
-                self.tools_list_dictionary = [cr_ca_schema, extract_variables_schema] + filtered
+                self.tools_list_dictionary = tools_list + filtered
         
         self.causal_max_loops = max_loops
         self.causal_graph: Dict[str, Dict[str, float]] = {}
@@ -1073,6 +1164,80 @@ class CRCAAgent(Agent):
             }
         }
 
+    @staticmethod
+    def _get_image_annotation_schema() -> Dict[str, Any]:
+        """Get schema for annotate_image tool."""
+        return {
+            "type": "function",
+            "function": {
+                "name": "annotate_image",
+                "description": "Annotate an image 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.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "image_path": {
+                            "type": "string",
+                            "description": "Path to image file, URL, or description of image location"
+                        },
+                        "output_format": {
+                            "type": "string",
+                            "enum": ["overlay", "json", "report", "all"],
+                            "default": "all",
+                            "description": "Output format: 'overlay' (numpy array), 'json' (structured data), 'report' (text), 'all' (AnnotationResult)"
+                        },
+                        "frame_id": {
+                            "type": "integer",
+                            "description": "Optional frame ID for temporal tracking in video sequences"
+                        }
+                    },
+                    "required": ["image_path"]
+                }
+            }
+        }
+    
+    @staticmethod
+    def _get_image_query_schema() -> Dict[str, Any]:
+        """Get schema for query_image tool."""
+        return {
+            "type": "function",
+            "function": {
+                "name": "query_image",
+                "description": "Answer a specific query about an image using natural language. Performs annotation first, then analyzes the results to answer questions like 'find the largest building', 'measure dimensions', 'count objects', etc.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "image_path": {
+                            "type": "string",
+                            "description": "Path to image file, URL, or description of image location"
+                        },
+                        "query": {
+                            "type": "string",
+                            "description": "Natural language query about the image (e.g., 'find the largest building and measure its dimensions', 'count how many circles are in the image', 'identify all lines and measure their lengths')"
+                        },
+                        "frame_id": {
+                            "type": "integer",
+                            "description": "Optional frame ID for temporal tracking"
+                        }
+                    },
+                    "required": ["image_path", "query"]
+                }
+            }
+        }
+    
+    @staticmethod
+    def _get_image_annotation_engine() -> Optional[Any]:
+        """Get or create singleton image annotation engine instance."""
+        global _image_annotation_engine
+        if not IMAGE_ANNOTATION_AVAILABLE:
+            return None
+        if _image_annotation_engine is None:
+            try:
+                _image_annotation_engine = ImageAnnotationEngine()
+            except Exception as e:
+                logger.error(f"Failed to initialize image annotation engine: {e}")
+                return None
+        return _image_annotation_engine
+    
     @staticmethod
     def _get_extract_variables_schema() -> Dict[str, Any]:
         """

MODEL_CARD.md

@@ -0,0 +1,53 @@
+---
+language: en
+license: apache-2.0
+tags:
+  - reasoning
+  - react
+  - causal-inference
+  - tool-use
+---
+
+# CR-CA LRM (draft model card)
+
+## Model summary
+This release pairs a **ReAct + self‑critique reasoning kernel** with a full-finetuned model.
+The system is designed to **orchestrate tools** and **enforce refusal‑first causal outputs**.
+
+**Base model:** Qwen2.5-7B-Instruct  
+**Finetune type:** full finetune (no LoRA adapters)  
+**Context length:** 8k
+
+## Intended use
+- Planning and reasoning over structured causal tasks.
+- Tool‑augmented reasoning with strict gating.
+
+## Limitations
+- Numeric causal outputs are refused unless validated by `crca_core`.
+- Reasoning traces are **non‑scientific** metadata and must not be treated as proofs.
+
+## Training data
+Hybrid dataset:
+- Internal ReAct traces (reason/act/observe/critique) with refusal labels.
+- Public reasoning datasets (see dataset builder config).
+
+## Evaluation
+Mixed evaluation:
+- Refusal accuracy.
+- ReAct cycle convergence.
+- Causal identification correctness on synthetic SCMs.
+
+## Usage
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+
+model_id = "YOUR_HF_REPO"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id)
+
+prompt = "Reason step-by-step and propose a tool call."
+inputs = tokenizer(prompt, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=256)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+

PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: crca
-Version: 1.4.0
-Summary: CR-CA Lite — lightweight causal reasoning agent with advanced analysis suite (CR-CA)
+Version: 1.5.0
+Summary: CR-CA Wrapper for CR-CA LRM on HF (Depricated)
 Project-URL: Homepage, https://github.com/IlumCI/CR-CA
 Project-URL: Repository, https://github.com/IlumCI/CR-CA
 Project-URL: Documentation, https://github.com/IlumCI/CR-CA/blob/main/README.md
@@ -24,7 +24,10 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: accelerate>=0.26.0
+Requires-Dist: causal-learn>=0.1.3.9
 Requires-Dist: ccxt>=4.0
+Requires-Dist: datasets>=2.16.0
 Requires-Dist: dowhy>=0.8
 Requires-Dist: geoip2>=4.7.0
 Requires-Dist: lightgbm>=4.0
@@ -38,6 +41,7 @@ Requires-Dist: numpy>=1.23
 Requires-Dist: openai>=1.0.0
 Requires-Dist: optuna>=3.0
 Requires-Dist: pandas>=1.5
+Requires-Dist: peft>=0.9.0
 Requires-Dist: pillow>=10.0
 Requires-Dist: praw>=7.0
 Requires-Dist: psutil>=5.9.0
@@ -57,9 +61,11 @@ Requires-Dist: scipy>=1.10
 Requires-Dist: seaborn>=0.11
 Requires-Dist: shodan>=1.30.0
 Requires-Dist: swarms
+Requires-Dist: tigramite>=5.2.0
 Requires-Dist: toml>=0.10.2
 Requires-Dist: torch>=2.0.0
 Requires-Dist: tqdm>=4.65.0
+Requires-Dist: transformers>=4.39.0
 Requires-Dist: web3>=6.0
 Requires-Dist: websockets>=11.0
 Requires-Dist: xgboost>=2.0

RELEASE_NOTES.md

@@ -0,0 +1,17 @@
+## v1.0 Release Notes (draft)
+
+### Core Features
+- In-house identification with proof objects and conservative scope labeling.
+- Real discovery backends: causal-learn (tabular) and tigramite (time-series).
+- Linear-Gaussian SCM counterfactuals with partial-abduction mode (optional).
+- Estimation/refutation gated by identification results.
+- Schema exports + generated documentation + benchmark harness outputs.
+
+### Non-Authoritative LLM Layer
+- DraftSpec generation only.
+- Tool orchestration is gated by LockedSpec and refusal rules.
+
+### Known Limitations
+- ID algorithm is conservative for latent-confounded cases.
+- Discovery outputs are hypotheses and require assumptions.
+

STABILITY.md

@@ -0,0 +1,19 @@
+## CR-CA v1.0 Stability Policy
+
+This document defines what **stable** means for the v1.0 release.
+
+### Stable Guarantees
+- **Structured outputs only**: all core results are JSON/Pydantic structures.
+- **Refusal-first**: numeric causal outputs are refused unless prerequisites are met.
+- **SCM-required counterfactuals**: counterfactuals require explicit structural equations.
+- **Identification gating**: estimation requires an `IdentificationResult`.
+
+### Known Limits (by design)
+- **Identification is conservative**: latent-confounded cases often return non-identifiable.
+- **Discovery is hypothesis-only**: outputs are not causal truth, only hypotheses under assumptions.
+- **LLM layer is non-authoritative**: drafts and orchestration only; no numeric causal claims.
+
+### Compatibility
+- Schema contracts are versioned via the exported JSON schemas in `schemas_export/crca_core`.
+- Changes that alter semantics must increment schema versions before release.
+