DAO Proposals & Community

View active proposals, submit new ideas, and connect with the SWARMS community.

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

about 2 hours ago0 comments

documentation

agents

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 --------------------- ```mermaid 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 ``` 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 ```mermaid 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} ``` 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 ---------------------- ```bash # 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: https://github.com/kyegomez/swarms/issues/1169  ---- 📚 Documentation preview 📚: https://swarms--1233.org.readthedocs.build/en/1233/

Proposed by IlumCI

DAO Proposals & Community

Discord Community

GitHub Repository

Twitter

Documentation