# SuperAgentic

Single-orchestrator architecture for simulation systems with data analytics and knowledge graph capabilities.

## Philosophy

**Single agent. Dynamic reasoning. Tools execute, you decide.**

- One orchestrator decides workflow based on query type
- Agent writes all SQL, Python, and Cypher queries
- Tools only execute - no LLM inside tools
- Session persistence with paths passed between tools
- Discovery-first: agent learns domain from tool results

---

## Architecture

```
+------------------------------------------------------------------+
|                          SUPERAGENTIC                             |
|                                                                   |
|  +-------------------------+    +------------------------------+  |
|  |     AGENT SERVER        |    |    DIGITAL TWIN SERVER       |  |
|  |                         |    |                              |  |
|  |  +-------------------+  |    |  +------------------------+  |  |
|  |  |   LangGraph       |  |    |  |   MCP SERVER           |  |  |
|  |  |   Workflow        |  |    |  |   (19 tools)           |  |  |
|  |  +-------------------+  |    |  |                        |  |  |
|  |          |              |    |  |  Discovery (5)         |  |  |
|  |  +-------------------+  |    |  |  Data (5)              |  |  |
|  |  |   Orchestrator    |--+--->|  |  Configuration (5)     |  |  |
|  |  |   (ReAct Agent)   |  |    |  |  Simulation (2)        |  |  |
|  |  +-------------------+  |    |  |  Core (2)              |  |  |
|  |                         |    |  +------------------------+  |  |
|  |  core/                  |    |  digitaltwin/                |  |
|  +-------------------------+    +------------------------------+  |
+------------------------------------------------------------------+
```

---

## Tools

### Core (2)
| Tool | Purpose |
|------|---------|
| `task_completed(summary)` | Signal completion (required at end) |
| `ask_user(question)` | Request clarification (use sparingly) |

### Discovery (5)
| Tool | Purpose |
|------|---------|
| `list_options()` | Available controllers, scenarios, faults, profiles |
| `get_sql_schema(file?)` | List data files or get specific schema |
| `get_kg_schema()` | Knowledge Graph structure |
| `list_session_artifacts()` | What's saved in session |
| `get_data_preview(path)` | Column names and sample data |

### Data (5)
| Tool | Purpose |
|------|---------|
| `get_sql_data(file, sql)` | Query data, returns `saved_path` |
| `execute_analytics(code, input_path?)` | Run Python calculations, returns `output_path` |
| `execute_visualization(code, input_path?)` | Create plots, returns `plot_path` |
| `get_kg_insights(cypher)` | Read from Knowledge Graph |
| `store_kg_insights(cypher)` | Write to Knowledge Graph |

### Configuration (5)
| Tool | Purpose |
|------|---------|
| `configure(config_json)` | Unified JSON configuration |
| `configure_controller(type, ...)` | Set controller with params |
| `configure_scenario(type, ...)` | Set workload scenario |
| `configure_faults(...)` | Inject actuator faults |
| `configure_plant(...)` | Set plant physics |

### Simulation (2)
| Tool | Purpose |
|------|---------|
| `run_simulation(steps?)` | Execute simulation |
| `compute_metrics(profile?)` | Compute performance metrics |

---

## Data Flow

```
get_sql_data ──────> saved_path
                        │
                        v
execute_analytics ──> output_path
                        │
                        v
get_data_preview ──> column names
                        │
                        v
execute_visualization ──> plot_path
```

Always pass paths between tools. Don't reload data unnecessarily.

---

## Workflow Patterns

### Data Analysis
```
get_sql_schema() → get_sql_data(file, sql) → saved_path
execute_analytics(code, input_path) → output_path
get_data_preview(output_path) → column names
execute_visualization(code, input_path) → plot_path
task_completed(findings)
```

### Simulation
```
list_options()
configure_controller/scenario/faults
run_simulation()
compute_metrics()
task_completed(results)
```

### Follow-Up Query
```
list_session_artifacts() → find existing paths
get_data_preview(path) → learn columns
execute_visualization(code, input_path) → create plot
task_completed(summary)
```

---

## Session Artifacts

All artifacts saved to `digitaltwin/sessions/<session_id>/`:

```
sessions/session_YYYYMMDD_HHMMSS/
├── session.json           # Metadata & event log
├── data_snapshots/        # SQL query results (JSON)
├── analysis_code/         # Generated Python code
├── analysis_data/         # Analytics outputs (JSON)
├── visualization_code/    # Generated plot code
└── visualizations/        # Saved plots (PNG/HTML)
```

---

## Quick Start

```bash
# Install dependencies
pip install -r requirements.txt
pip install -r digitaltwin/requirements.txt

# Set API key
export GROQ_API_KEY=your_key

# Run interactive mode
python agent.py

# Single query
python agent.py -q "Analyze temperature patterns"
```

---

## Environment Variables

```bash
# Required
GROQ_API_KEY=your_key

# Optional
GROQ_MODEL=model_name
LLM_PROVIDER=groq  # or "openai"
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
```

---

## Directory Structure

```
superAgentic/
├── agent.py                # Entry point
├── core/                   # Agent intelligence
│   ├── workflow.py         # LangGraph workflow
│   ├── nodes.py            # ReAct agent node
│   ├── state.py            # State definition
│   ├── context.py          # Event history
│   ├── prompts.py          # System prompt
│   ├── mcp_manager.py      # Tool discovery
│   └── agent_cards.py      # Agent configuration
│
└── digitaltwin/            # Domain implementation
    ├── config/
    │   ├── __init__.py     # Config loader
    │   └── domain_config.yaml
    ├── tools/mcp_server.py # MCP tools
    ├── sessions/           # Session persistence
    ├── data/               # Data files
    ├── simulation/         # Physics engine
    ├── controllers/        # Control algorithms
    ├── runtime/            # Unified runtime
    └── kg/                 # Knowledge Graph
```

---

## Design Principles

| Principle | Rationale |
|-----------|-----------|
| Single Orchestrator | Sequential workflows are optimal for single agent |
| Agent Writes, Tools Execute | All reasoning in orchestrator, tools just run code |
| Discovery First | Fetch schema/options before writing queries |
| Preview Before Viz | Get exact column names to avoid empty plots |
| Session Persistence | Pass paths between tools, avoid context overflow |
| Follow-Up Awareness | Check artifacts before redoing work |