Revise CRCAAgent documentation for clarity and updates

Updated documentation for CRCAAgent to reflect new features and changes, including LLM integration and dual-mode operation.

docs/swarms/agents/cr_ca_agent.md

@@ -1,120 +1,160 @@
-
+<!-- swarms/agents/cr_ca_agent.py — CRCAAgent (CR‑CA Lite) -->
-# CRCAgent
+# CRCAAgent 
 
 Short summary
 -------------
-CRCAgent is a lightweight, auditable causal simulation core implemented in
+CRCAAgent is a lightweight causal reasoning Agent with LLM integration,
-pure Python and intended as the deterministic CR‑CA engine for Swarms.
+implemented in pure Python and intended as a flexible CR‑CA engine for Swarms.
-It focuses on the core ASTT primitives: a causal DAG, a linear structural
+It provides both LLM-based causal analysis and deterministic causal simulation,
+focusing on the core ASTT primitives: a causal DAG, a linear structural
 evolution operator (in z-space), and compact counterfactual generation.
 
 Key properties
-- Minimal dependencies (numpy + stdlib)
+- LLM integration for sophisticated causal reasoning (like full CRCAAgent)
+- Dual-mode operation: LLM-based analysis and deterministic simulation
+- Minimal dependencies (numpy + swarms Agent base)
 - Pure-Python causal graph (adjacency dicts)
 - Linear SCM evolution by default (overrideable)
-- Agent-first `run()` entrypoint (accepts dict or JSON payloads)
+- Agent-first `run()` entrypoint (accepts task string or dict/JSON payloads)
 
 Canonical import
 ----------------
 Use the canonical agent import in application code:
 
 ```python
-from swarms.agents.cr_ca_agent import CRCAgent
+from swarms.agents.cr_ca_agent import CRCAAgent
 ```
 
 Quickstart
 ----------
-Minimal example — initialize, add edges, evolve state and get counterfactuals:
+Minimal example — deterministic mode: initialize, add edges, evolve state and get counterfactuals:
 
 ```python
-from swarms.agents.cr_ca_agent import CRCAgent
+from swarms.agents.cr_ca_agent import CRCAAgent
 
-agent = CRCAgent(variables=["price", "demand", "inventory"])
+agent = CRCAAgent(variables=["price", "demand", "inventory"])
 agent.add_causal_relationship("price", "demand", strength=-0.5)
 agent.add_causal_relationship("demand", "inventory", strength=-0.2)
 
 state = {"price": 100.0, "demand": 1000.0, "inventory": 5000.0}
-out = agent.run(state, target_variables=["price", "demand"], max_steps=1)
+out = agent.run(initial_state=state, target_variables=["price", "demand"], max_steps=1)
 
 print("Evolved:", out["evolved_state"])            # evolved world state
 for sc in out["counterfactual_scenarios"][:5]:      # candidate CFs
     print(sc.name, sc.interventions, sc.probability)
 ```
 
+LLM-based causal analysis example
+----------------------------------
+
+```python
+from swarms.agents.cr_ca_agent import CRCAAgent
+
+agent = CRCAAgent(
+    variables=["price", "demand", "inventory"],
+    model_name="gpt-4o",
+    max_loops=3
+)
+agent.add_causal_relationship("price", "demand", strength=-0.5)
+
+# LLM mode: pass task as string
+task = "Analyze how increasing price affects demand and inventory levels"
+result = agent.run(task=task)
+
+print("Causal Analysis:", result["causal_analysis"])
+print("Counterfactual Scenarios:", result["counterfactual_scenarios"])
+print("Analysis Steps:", result["analysis_steps"])
+```
+
 Agent-style JSON payload example (orchestrators)
 ------------------------------------------------
 
 ```python
 import json
-from swarms.agents.cr_ca_agent import CRCAgent
+from swarms.agents.cr_ca_agent import CRCAAgent
 
-agent = CRCAgent(variables=["price","demand","inventory"])
+agent = CRCAAgent(variables=["price","demand","inventory"])
 payload = json.dumps({"price": 100.0, "demand": 1000.0})
-out = agent.run(payload, target_variables=["price"], max_steps=1)
+out = agent.run(initial_state=payload, target_variables=["price"], max_steps=1)
 print(out["evolved_state"])
 ```
 
 Why use `run()`
 --------------
-- Accepts both dict and JSON payloads for flexible integration.
+- **Dual-mode operation**: Automatically selects LLM mode (task string) or deterministic mode (initial_state dict)
-- Evolves the world state for `max_steps` using the deterministic evolution
+- **LLM mode**: Performs sophisticated multi-loop causal reasoning with structured output
-  operator, then generates counterfactuals from the evolved state (consistent timelines).
+- **Deterministic mode**: Evolves the world state for `max_steps` using the deterministic evolution
-- Returns a compact result dict used across Swarms agents.
+  operator, then generates counterfactuals from the evolved state (consistent timelines)
+- Accepts both dict and JSON payloads for flexible integration
+- Returns a compact result dict used across Swarms agents
 
 Architecture (high level)
 -------------------------
 
 ```mermaid
-flowchart LR
+flowchart TB
-  subgraph Ingestion["Input / Ingestion"]
+  subgraph Input[Input]
-    I1["Initial state"]
+    I1[Task string]
-    I2["Historical data"]
+    I2[Initial state dict]
   end
 
-  subgraph Modeling["Causal Model"]
+  I1 -->|String| LLM[LLM Mode]
-    G1["Causal graph"]
+  I2 -->|Dict| DET[Deterministic Mode]
-    G2["Add/update edges"]
-    G3["Standardization stats"]
-  end
 
-  subgraph Preproc["Preprocessing"]
+  subgraph LLMFlow[LLM Causal Analysis]
-    P1["ensure_standardization_stats"]
+    LLM --> P1[Build Causal Prompt]
-    P2["Standardize to z-space"]
+    P1 --> L1[LLM Step 1]
+    L1 --> L2[LLM Step 2...N]
+    L2 --> SYN[Synthesize Analysis]
+    SYN --> CF1[Generate Counterfactuals]
   end
 
-  subgraph Engine["Lite Engine"]
+  subgraph DetFlow[Deterministic Simulation]
-    T["Topological sort"]
+    DET --> P2[ensure_standardization_stats]
-    E["predict_outcomes (linear SCM)"]
+    P2 --> P3[Standardize to z-space]
-    D["De-standardize outputs"]
+    P3 --> T[Topological sort]
-    R["run (timeline rollout)"]
+    T --> E[predict_outcomes linear SCM]
+    E --> D[De-standardize outputs]
+    D --> R[Timeline rollout]
+    R --> CF2[Generate Counterfactuals]
   end
 
-  subgraph CF["Counterfactuals"]
+  subgraph Model[Causal Model]
-    C1["generate_counterfactual_scenarios"]
+    G1[Causal graph]
-    C2["Abduction–Action–Prediction"]
+    G2[Edge strengths]
-    S["Scenario scoring"]
+    G3[Standardization stats]
   end
 
-  subgraph Analysis["Outputs / Analysis"]
+  subgraph Output[Outputs]
-    O1["Evolved state"]
+    O1[Causal analysis / Evolved state]
-    O2["Counterfactual scenarios"]
+    O2[Counterfactual scenarios]
-    O3["Causal paths / visualization"]
+    O3[Causal graph info]
   end
 
-  I1 --> P1 --> P2 --> G1
+  G1 --> LLMFlow
-  I2 --> G2 --> G1
+  G1 --> DetFlow
-  G3 --> P2
+  G2 --> DetFlow
-  G1 --> T --> E --> D --> R
+  G3 --> DetFlow
-  R --> C1 --> C2 --> S --> O2
+  CF1 --> O2
+  CF2 --> O2
+  SYN --> O1
   R --> O1
-  T --> O3
+  G1 --> O3
-
 ```
 
 Complete method index (quick)
 -----------------------------
-The following is the public surface implemented by `CRCAgent` in
+The following is the public surface implemented by `CRCAAgent` (Lite) in
-`swarms/agents/cr_ca_agent.py`. See the code for full docstrings and math.
+`ceca_lite/crca-lite.py` (canonical import: `swarms/agents/cr_ca_agent.py`).
+See the code for full docstrings and math.
+
+LLM integration
+- `_get_cr_ca_schema()` — CR-CA function calling schema for structured reasoning
+- `step(task)` — Execute a single step of LLM-based causal reasoning
+- `_build_causal_prompt(task)` — Build causal analysis prompt with graph context
+- `_build_memory_context()` — Build memory context from previous analysis steps
+- `_synthesize_causal_analysis(task)` — Synthesize final causal analysis using LLM
+- `_run_llm_causal_analysis(task)` — Run multi-loop LLM-based causal analysis
 
 Core graph & state
 - `_ensure_node_exists(node)` — ensure node present in internal maps
@@ -142,14 +182,23 @@ Estimation, analysis & utilities
 - `identify_causal_chain(start, end)` — BFS shortest path
 - `detect_change_points(series, threshold=2.5)` — simple detector
 
-Advanced functions (Restricted((Does exist)))
+Advanced (optional / Pro)
 - `learn_structure(...)`, `plan_interventions(...)`, `gradient_based_intervention_optimization(...)`,
   `convex_intervention_optimization(...)`, `evolutionary_multi_objective_optimization(...)`,
   `probabilistic_nested_simulation(...)`, `deep_root_cause_analysis(...)`, and more.
 
 Return shape from `run()`
 -------------------------
-`run()` returns a dictionary with at least the following keys:
+`run()` returns a dictionary with different keys depending on mode:
+
+**LLM Mode** (when `task` is a string):
+- `task`: the provided task/problem string
+- `causal_analysis`: synthesized causal analysis report (string)
+- `counterfactual_scenarios`: list of `CounterfactualScenario` objects
+- `causal_graph_info`: {"nodes": [...], "edges": [...], "is_dag": bool}
+- `analysis_steps`: list of analysis steps with memory context
+
+**Deterministic Mode** (when `initial_state` is a dict):
 - `initial_state`: the provided input state (dict)
 - `evolved_state`: state after applying `max_steps` of the evolution operator
 - `counterfactual_scenarios`: list of `CounterfactualScenario` with name/interventions/expected_outcomes/probability/reasoning
@@ -158,28 +207,45 @@ Return shape from `run()`
 
 Usage patterns & examples
 -------------------------
-1) Script-style (preferred for simple programs)
+1) LLM-based causal analysis (sophisticated reasoning)
 
 ```python
-agent = CRCAgent(variables=["a","b","c"])
+agent = CRCAAgent(
+    variables=["a","b","c"],
+    model_name="gpt-4o",
+    max_loops=3
+)
+agent.add_causal_relationship("a","b", strength=0.8)
+
+# LLM mode: pass task as string
+task = "Analyze the causal relationship between a and b"
+res = agent.run(task=task)
+print(res["causal_analysis"])
+print(res["analysis_steps"])
+```
+
+2) Deterministic simulation (script-style)
+
+```python
+agent = CRCAAgent(variables=["a","b","c"])
 agent.add_causal_relationship("a","b", strength=0.8)
 state = {"a":1.0, "b":2.0, "c":3.0}
-res = agent.run(state, max_steps=2)
+res = agent.run(initial_state=state, max_steps=2)
 print(res["evolved_state"])
 ```
 
-2) Orchestration / agent-style (JSON payloads)
+3) Orchestration / agent-style (JSON payloads)
 
 ```python
 payload = '{"a":1.0,"b":2.0,"c":3.0}'
-res = agent.run(payload, max_steps=1)
+res = agent.run(initial_state=payload, max_steps=1)
 if "error" in res:
     print("Bad payload:", res["error"])
 else:
     print("Evolved:", res["evolved_state"])
 ```
 
-3) Lower-level testing & research
+4) Lower-level testing & research
 
 ```python
 pred = agent._predict_outcomes({"a":1.0,"b":2.0},{"a":0.0})
@@ -188,19 +254,28 @@ print(pred)
 
 Design notes & limitations
 --------------------------
-- Linearity: default `_predict_outcomes` is linear in standardized z-space. To model non-linear dynamics, subclass `CRCAgent` and override `_predict_outcomes`.
+- **LLM Integration**: Uses swarms Agent infrastructure for LLM calls. Configure model via `model_name` parameter. Multi-loop reasoning enabled by default.
-- Probabilities: scenario probability is a heuristic proximity measure (Mahalanobis-like) — not a formal posterior.
+- **Dual-mode operation**: Automatically selects LLM mode (task string) or deterministic mode (initial_state dict). Both modes generate counterfactuals using deterministic methods.
-- Stats: the engine auto-fills standardization stats with sensible defaults (`mean=observed`, `std=1.0`) via `ensure_standardization_stats` to avoid degenerate std=0 cases.
+- **Linearity**: default `_predict_outcomes` is linear in standardized z-space. To model non-linear dynamics, subclass `CRCAAgent` and override `_predict_outcomes`.
-- Dependencies: Lite intentionally avoids heavy libs (pandas/scipy/cvxpy/LLM) in the core file.
+- **Probabilities**: scenario probability is a heuristic proximity measure (Mahalanobis-like) — not a formal posterior.
+- **Stats**: the engine auto-fills standardization stats with sensible defaults (`mean=observed`, `std=1.0`) via `ensure_standardization_stats` to avoid degenerate std=0 cases.
+- **Dependencies**: Lite intentionally avoids heavy libs (pandas/scipy/cvxpy) but includes LLM integration via swarms Agent base.
 
 Extending & integration
 -----------------------
 For advanced capabilities (structure learning, Bayesian inference, optimization,
-LLM-driven analysis), build separate modules that import `CRCAgent` as the
+extensive statistical methods), use the full `CRCAAgent` in `swarms/agents/cr_ca_agent.py`.
-deterministic simulation core and add the richer logic there (keeps Lite auditable).
+The Lite version provides core causal reasoning with LLM support while maintaining minimal dependencies.
 
 References
 ----------
 - Pearl, J. (2009). *Causality: Models, Reasoning, and Inference*.
 - Pearl, J., & Mackenzie, D. (2018). *The Book of Why*.
 
+---
+CRCAAgent (Lite) — lightweight causal reasoning Agent with LLM integration for Swarms.
+
+Implementation: `ceca_lite/crca-lite.py`  
+Canonical import: `from swarms.agents.cr_ca_agent import CRCAAgent`
+
+