[FEAT-AGENT][Added Lightweight CRCA Agent reasoning architecture]

[IlumCI]

description

Introduces a lightweight causal reasoning Agent implementing the core ASTT/CR-CA primitives with LLM integration. This Agent provides both deterministic causal simulation and LLM-based causal analysis, enabling flexible causal reasoning workflows without requiring networkx, pandas, scipy, cvxpy, or other heavyweight libraries.

Background / Motivation

The existing CRCAAgent in swarms/agents/cr_ca_agent.py provides full-featured causal reasoning with LLM integration, advanced optimization, and extensive statistical methods. However, many use cases require a deterministic, dependency-light agent that provides core causal simulation capabilities without external API calls.

This PR introduces CRCAAgent (Lite) as a lightweight Agent in the swarms framework that:

• Implements the full Agent interface with run() method supporting both LLM-based and deterministic modes
• Provides LLM integration for sophisticated causal reasoning (like the full version)
• Supports deterministic causal simulation without external API calls
• Requires only numpy and swarms Agent base (no networkx, pandas, scipy, cvxpy)
• Provides predictable, reproducible results for deterministic workflows
• Serves as a flexible causal reasoning Agent that can operate with or without LLM calls

The Lite implementation maintains mathematical rigor while prioritizing simplicity and performance, making it a versatile Agent for causal reasoning that combines LLM capabilities with deterministic simulation.

Architecture Overview

graph TB
    A[Task/Initial State] --> B{Mode Selection}
    B -->|LLM Mode| C[Build Causal Prompt]
    B -->|Deterministic Mode| D[Standardize to z-space]
    
    C --> E[LLM Causal Analysis]
    E --> F[Multi-loop Reasoning]
    F --> G[Synthesize Analysis]
    G --> H[Generate Counterfactuals]
    
    D --> I[Topological Sort]
    I --> J[Linear SCM Propagation]
    J --> K[De-standardize]
    K --> L[Evolved State]
    L --> M[Counterfactual Generation]
    
    N[Causal Graph] --> I
    N --> O[Edge Strengths]
    O --> J
    N --> C
    
    style A fill:#e1f5ff
    style L fill:#c8e6c9
    style M fill:#fff9c4
    style G fill:#ffcccb

Loading

Core Components

The implementation centers on four key capabilities:

1. LLM-Based Causal Analysis: Multi-loop reasoning with structured output

   • Uses CR-CA schema for function calling
   • Builds causal prompts with graph context
   • Synthesizes comprehensive causal analysis reports
   • Supports memory context across reasoning loops

2. Evolution Operator E(x): Implements linear structural causal model (SCM) in standardized z-space

   • Formula: z_y = Σᵢ βᵢ·z_xi where βᵢ are edge strengths
   • Topological ordering ensures causal dependencies are respected
   • Standardization provides numerical stability and scale-invariance

3. Counterfactual Generation: Implements Pearl's do-operator and abduction-action-prediction

   • Generates intervention scenarios with probability estimates
   • Uses Mahalanobis-like distance for plausibility scoring
   • Supports multi-variable interventions and cascading effects

4. Causal Graph Operations: Pure-Python DAG implementation

   • Adjacency dictionary representation (no external graph libraries)
   • Topological sort via Kahn's algorithm
   • Path finding via BFS for causal chain identification

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Graph
    participant SCM
    
    User->>Agent: run(task/initial_state)
    alt LLM Mode (task string)
        Agent->>Agent: _build_causal_prompt()
        loop max_loops
            Agent->>LLM: step(prompt)
            LLM-->>Agent: causal_analysis
            Agent->>Agent: update_memory_context()
        end
        Agent->>LLM: synthesize_analysis()
        LLM-->>Agent: final_analysis
        Agent->>Agent: generate_counterfactual_scenarios()
    else Deterministic Mode (initial_state dict)
        Agent->>Graph: topological_sort()
        Graph-->>Agent: ordered_nodes
        Agent->>SCM: _predict_outcomes(state, {})
        SCM->>SCM: standardize(state)
        SCM->>SCM: propagate(parents → children)
        SCM->>SCM: de-standardize(predictions)
        SCM-->>Agent: evolved_state
        Agent->>Agent: generate_counterfactual_scenarios()
    end
    Agent-->>User: {analysis/evolved_state, counterfactuals, graph_info}

Loading

What changed (files)

• ceca_lite/crca-lite.py — Core Lite implementation (CRCAgent class)
• swarms/agents/cr_ca_agent.py — Integration point (CRCAAgent class reference)
• docs/swarms/agents/crca_agent.md — Documentation and usage examples

Key Design Decisions

Pure-Python Graph Representation

• Uses nested dictionaries {node: {child: strength}} instead of networkx
• Enables zero external dependencies beyond numpy
• Provides O(1) edge lookups and O(V+E) topological operations

Standardized Linear SCM

• All computations occur in z-space (standardized values)
• Prevents numerical instability from scale mismatches
• Allows direct comparison of causal effects across variables
• Linear model is intentionally simple; non-linear extensions can subclass

Dual-Mode Operation

• LLM mode: Multi-loop causal reasoning with structured output (like full CRCAAgent)
• Deterministic mode: Pure causal simulation without LLM calls
• Automatic mode selection based on input type (string vs dict)
• Both modes generate counterfactual scenarios using deterministic methods

LLM Integration

• Uses CR-CA schema for structured function calling
• Multi-loop reasoning with memory context
• Synthesizes comprehensive causal analysis reports
• Compatible with swarms Agent LLM infrastructure

Agent-First API

• run() method accepts task string (LLM mode) or initial_state dict (deterministic mode)
• Returns structured output matching Swarms agent conventions
• Supports max_loops parameter for multi-step LLM reasoning or evolution

Value Proposition

Performance Characteristics

• Forward pass: O(V + E) where V = variables, E = edges (deterministic mode)
• Memory: O(V + E) for graph representation
• LLM mode: Network latency depends on model provider
• Suitable for both high-frequency simulation and sophisticated causal analysis

Integration Benefits

• Minimal dependency footprint (numpy + swarms Agent base)
• LLM integration enables sophisticated causal reasoning
• Deterministic mode enables reproducible testing
• Pure Python graph implementation simplifies debugging
• Flexible dual-mode operation adapts to use case

Use Cases Enabled

• LLM-based causal analysis for complex problems
• Real-time deterministic causal simulation in production systems
• Testing and validation of causal models
• Educational and research applications requiring transparency
• Systems requiring both LLM reasoning and deterministic simulation

Testing and validation

# Unit tests
pytest tests/ -k crca

# Linting
make lint && make format

# Quick validation
python -c "
from swarms.agents.cr_ca_agent import CRCAAgent
agent = CRCAAgent(variables=['price', 'demand', 'inventory'])
agent.add_causal_relationship('price', 'demand', strength=-0.5)
result = agent.run({'price': 100.0, 'demand': 1000.0, 'inventory': 5000.0})
assert 'evolved_state' in result
assert 'counterfactual_scenarios' in result
print('✓ Core functionality validated')
"

Security & Performance

• LLM Mode: Uses swarms Agent LLM infrastructure (secure, configurable)
• Deterministic Mode: No external API calls, fully deterministic operations
• Safe: Pure Python computation, no code execution or deserialization risks
• Performant: O(V+E) complexity for deterministic operations, minimal memory overhead
• Scalable: Handles graphs with hundreds of variables efficiently

Compatibility & Breaking Changes

• New module: Introduces CRCAAgent class at swarms/agents/cr_ca_agent.py
• No breaking changes: Existing CRCAAgent (full version) remains unchanged
• Import path: from swarms.agents.cr_ca_agent import CRCAAgent
• Backward compatible: Existing code using full CRCAAgent continues to work

Documentation

• Quickstart guide in docs/swarms/agents/crca_agent.md
• API reference with mathematical foundations
• Example usage patterns for common scenarios
• Integration guide for orchestrator systems

Checklist (required before merge)

• Code builds and passes unit tests: make test
• Linting and formatting checks pass: make lint / make format
• Documentation updated and examples validated
• Performance benchmarks documented (if applicable)
• No references to deprecated paths remain
• Release notes / changelog entry added

Reviewer guidance

Critical areas for review:

1. _predict_outcomes correctness

   • Verify topological ordering is respected
   • Check standardization/de-standardization round-trip accuracy
   • Validate do-operator semantics (interventions break parent dependencies)

2. Counterfactual generation

   • Ensure intervention space exploration is systematic
   • Verify probability calculations are bounded and reasonable
   • Check edge cases (zero std, missing stats)

3. Graph operations

   • Validate topological sort handles all DAG cases
   • Verify cycle detection in is_dag()
   • Check path finding correctness

4. API design

   • Confirm run() method signature matches agent conventions
   • Verify return structure is consistent with Swarms patterns
   • Check error handling for invalid inputs

5. Dependencies

   • Confirm only numpy + swarms.structs.agent are required (LLM via Agent base)
   • Verify no hidden imports or optional dependencies (networkx, pandas, scipy, cvxpy)
   • Check LLM integration uses swarms Agent infrastructure correctly

6. LLM Integration

   • Verify CR-CA schema is correctly defined and used
   • Check multi-loop reasoning works as expected
   • Validate prompt building and memory context
   • Ensure both LLM and deterministic modes work correctly

Notes for maintainers

• CRCAAgent (Lite) is a full Agent in the swarms framework with run() method supporting both LLM and deterministic modes
• This Lite implementation provides essential causal reasoning capabilities with LLM integration (like full version)
• Full-featured CRCAAgent adds advanced optimization, statistical methods, and extensive features on top
• Lite version provides core causal reasoning with LLM support while maintaining minimal dependencies
• Consider exporting from swarms/agents/__init__.py for canonical imports

Contacts / Authors

• Primary author: https://x.com/IlumTheProtogen
• Maintainer: @kyegomez

Optional: Link to issue(s)

• Issue: [FEAT][Paper implmentation] [ParallelMuse: Agentic Parallel Thinking for Deep Information Seeking] #1169

---

📚 Documentation preview 📚: https://swarms--1233.org.readthedocs.build/en/1233/

[github-advanced-security]

Pyre found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.