fix: environment setup

.claude/settings.local.json

@@ -2,7 +2,18 @@
   "permissions": {
     "allow": [
       "Bash(npm install:*)",
-      "Bash(npm test:*)"
+      "Bash(npm test:*)",
+      "Skill(building-agents-construction)",
+      "Skill(building-agents-construction:*)",
+      "Bash(PYTHONPATH=core:exports pytest:*)",
+      "mcp__agent-builder__create_session",
+      "mcp__agent-builder__get_session_status",
+      "mcp__agent-builder__set_goal",
+      "mcp__agent-builder__list_mcp_servers",
+      "mcp__agent-builder__test_node",
+      "mcp__agent-builder__add_node",
+      "mcp__agent-builder__add_edge",
+      "mcp__agent-builder__validate_graph"
     ]
   }
 }

.claude/skills/building-agents-construction/SKILL.md

@@ -16,15 +16,151 @@ Step-by-step guide for building goal-driven agent packages.
 
 **Prerequisites:** Read `building-agents-core` for fundamental concepts.
 
-## Step-by-Step Guide
+## CRITICAL: entry_points Format Reference
 
-### Step 1: Create Package Structure
+**⚠️ Common Mistake Prevention:**
 
-When user requests an agent, **immediately create the package**:
+The `entry_points` parameter in GraphSpec has a specific format that is easy to get wrong. This section exists because this mistake has caused production bugs.
+
+### Correct Format
 
 ```python
-# 1. Create directory
+entry_points = {"start": "first-node-id"}
+```
+
+**Examples from working agents:**
+
+```python
+# From exports/outbound_sales_agent/agent.py
+entry_node = "lead-qualification"
+entry_points = {"start": "lead-qualification"}
+
+# From exports/support_ticket_agent/agent.py (FIXED)
+entry_node = "parse-ticket"
+entry_points = {"start": "parse-ticket"}
+```
+
+### WRONG Formats (DO NOT USE)
+
+```python
+# ❌ WRONG: Using node ID as key with input keys as value
+entry_points = {
+    "parse-ticket": ["ticket_content", "customer_id", "ticket_id"]
+}
+# Error: ValidationError: Input should be a valid string, got list
+
+# ❌ WRONG: Using set instead of dict
+entry_points = {"parse-ticket"}
+# Error: ValidationError: Input should be a valid dictionary, got set
+
+# ❌ WRONG: Missing "start" key
+entry_points = {"entry": "parse-ticket"}
+# Error: Graph execution fails, cannot find entry point
+```
+
+### Validation Check
+
+After writing graph configuration, ALWAYS validate:
+
+```python
+# Check 1: Must be a dict
+assert isinstance(entry_points, dict), f"entry_points must be dict, got {type(entry_points)}"
+
+# Check 2: Must have "start" key
+assert "start" in entry_points, f"entry_points must have 'start' key, got keys: {entry_points.keys()}"
+
+# Check 3: "start" value must match entry_node
+assert entry_points["start"] == entry_node, f"entry_points['start']={entry_points['start']} must match entry_node={entry_node}"
+
+# Check 4: Value must be a string (node ID)
+assert isinstance(entry_points["start"], str), f"entry_points['start'] must be string, got {type(entry_points['start'])}"
+```
+
+**Why this matters:** GraphSpec uses Pydantic validation. The wrong format causes ValidationError at runtime, which blocks all agent execution and tests. This bug is not caught until you try to run the agent.
+
+## Building Session Management with MCP
+
+**MANDATORY**: Use the agent-builder MCP server's BuildSession system for automatic bookkeeping and persistence.
+
+### Available MCP Session Tools
+
+```python
+# Create new session (call FIRST before building)
+mcp__agent-builder__create_session(name="Support Ticket Agent")
+# Returns: session_id, automatically sets as active session
+
+# Get current session status (use for progress tracking)
+status = mcp__agent-builder__get_session_status()
+# Returns: {
+#   "session_id": "build_20250122_...",
+#   "name": "Support Ticket Agent",
+#   "has_goal": true,
+#   "node_count": 5,
+#   "edge_count": 7,
+#   "nodes": ["parse-ticket", "categorize", ...],
+#   "edges": [("parse-ticket", "categorize"), ...]
+# }
+
+# List all saved sessions
+mcp__agent-builder__list_sessions()
+
+# Load previous session
+mcp__agent-builder__load_session_by_id(session_id="build_...")
+
+# Delete session
+mcp__agent-builder__delete_session(session_id="build_...")
+```
+
+### How MCP Session Works
+
+The BuildSession class (in `core/framework/mcp/agent_builder_server.py`) automatically:
+- **Persists to disk** after every operation (`_save_session()` called automatically)
+- **Tracks all components**: goal, nodes, edges, mcp_servers
+- **Maintains timestamps**: created_at, last_modified
+- **Stores to**: `~/.claude-code-agent-builder/sessions/`
+
+When you call MCP tools like:
+- `mcp__agent-builder__set_goal(...)` - Automatically added to session.goal and saved
+- `mcp__agent-builder__add_node(...)` - Automatically added to session.nodes and saved
+- `mcp__agent-builder__add_edge(...)` - Automatically added to session.edges and saved
+
+**No manual bookkeeping needed** - the MCP server handles it all!
+
+### Show Progress to User
+
+```python
+# Get session status to show progress
+status = json.loads(mcp__agent-builder__get_session_status())
+
+print(f"\n📊 Building Progress:")
+print(f"   Session: {status['name']}")
+print(f"   Goal defined: {status['has_goal']}")
+print(f"   Nodes: {status['node_count']}")
+print(f"   Edges: {status['edge_count']}")
+print(f"   Nodes added: {', '.join(status['nodes'])}")
+```
+
+**Benefits:**
+- Automatic persistence - survive crashes/restarts
+- Clear audit trail - all operations logged
+- Session resume - continue from where you left off
+- Progress tracking built-in
+- No manual state management needed
+
+## Step-by-Step Guide
+
+### Step 1: Create Building Session & Package Structure
+
+When user requests an agent, **immediately create MCP session and package**:
+
+```python
+# 0. FIRST: Create MCP building session
 agent_name = "technical_research_agent"  # snake_case
+session_result = mcp__agent-builder__create_session(name=agent_name.replace('_', ' ').title())
+session_id = json.loads(session_result)["session_id"]
+print(f"✅ Created building session: {session_id}")
+
+# 1. Create directory
 package_path = f"exports/{agent_name}"
 
 Bash(f"mkdir -p {package_path}/nodes")
@@ -174,14 +310,22 @@ Edit(
 Open exports/technical_research_agent/agent.py to see the goal!
 ```
 
+**Note:** Goal is automatically tracked in MCP session. Use `mcp__agent-builder__get_session_status()` to check progress.
+
 ### Step 3: Add Nodes (Incremental)
 
-**⚠️ IMPORTANT:** Before adding any node with tools, you MUST:
+**⚠️ CRITICAL VALIDATION REQUIREMENTS:**
 
+Before adding any node with tools:
 1. Call `mcp__agent-builder__list_mcp_tools()` to discover available tools
 2. Verify each tool exists in the response
 3. If a tool doesn't exist, inform the user and ask how to proceed
 
+After writing each node:
+4. **MANDATORY**: Validate with `mcp__agent-builder__test_node()` before proceeding
+5. **MANDATORY**: Check MCP session status to track progress
+6. Only proceed to next node after validation passes
+
 For each node, **write immediately after approval**:
 
 ```python
@@ -234,24 +378,36 @@ Open exports/technical_research_agent/nodes/__init__.py to see it!
 
 **Repeat for each node.** User watches the file grow.
 
-#### Optional: Validate Node with MCP Tools
+#### MANDATORY: Validate Each Node with MCP Tools
 
-After writing a node, you can optionally use MCP tools for validation:
+After writing EVERY node, you MUST validate before proceeding:
 
 ```python
-# Node is already written to file. Now validate it:
-mcp__agent-builder__test_node(
+# Node is already written to file. Now VALIDATE IT (REQUIRED):
+validation_result = json.loads(mcp__agent-builder__test_node(
     node_id="analyze-request",
     test_input='{"query": "test query"}',
     mock_llm_response='{"analysis": "mock output"}'
-)
+))
 
-# Returns validation result showing node behavior
-# This is OPTIONAL - for bookkeeping/validation only
-# The node already exists in the file!
+# Check validation result
+if validation_result["valid"]:
+    # Show user validation passed
+    print(f"✅ Node validation passed: analyze-request")
+
+    # Show session progress
+    status = json.loads(mcp__agent-builder__get_session_status())
+    print(f"📊 Session progress: {status['node_count']} nodes added")
+else:
+    # STOP - Do not proceed until fixed
+    print(f"❌ Node validation FAILED:")
+    for error in validation_result["errors"]:
+        print(f"   - {error}")
+    print("⚠️ Must fix node before proceeding to next component")
+    # Ask user how to proceed
 ```
 
-**Key Point:** The node was written to `nodes/__init__.py` FIRST. The MCP tool is just for validation.
+**CRITICAL:** Do NOT proceed to the next node until validation passes. Bugs caught here prevent wasted work later.
 
 ### Step 4: Connect Edges
 
@@ -282,10 +438,15 @@ Edit(
 )
 
 # Write entry points and terminal nodes
+# ⚠️ CRITICAL: entry_points format must be {"start": "node_id"}
+# Common mistake: {"node_id": ["input_keys"]} is WRONG
+# Correct format: {"start": "first-node-id"}
+# Reference: See exports/outbound_sales_agent/agent.py for example
+
 graph_config = f'''
 # Graph configuration
 entry_node = "{entry_node_id}"
-entry_points = {entry_points}
+entry_points = {{"start": "{entry_node_id}"}}  # CRITICAL: Must be {{"start": "node-id"}}
 pause_nodes = {pause_nodes}
 terminal_nodes = {terminal_nodes}
 
@@ -311,20 +472,98 @@ Edit(
 5 edges connecting 6 nodes
 ```
 
-#### Optional: Validate Graph Structure
+#### MANDATORY: Validate Graph Structure
 
-After writing edges, optionally validate with MCP tools:
+After writing edges, you MUST validate before proceeding to finalization:
 
 ```python
-# Edges already written to agent.py. Now validate structure:
-mcp__agent-builder__validate_graph()
+# Edges already written to agent.py. Now VALIDATE STRUCTURE (REQUIRED):
+graph_validation = json.loads(mcp__agent-builder__validate_graph())
 
-# Returns: unreachable nodes, missing connections, etc.
-# This is OPTIONAL - for validation only
+# Check for structural issues
+if graph_validation["valid"]:
+    print("✅ Graph structure validated successfully")
+
+    # Show session summary
+    status = json.loads(mcp__agent-builder__get_session_status())
+    print(f"   - Nodes: {status['node_count']}")
+    print(f"   - Edges: {status['edge_count']}")
+    print(f"   - Entry point: {entry_node_id}")
+else:
+    print("❌ Graph validation FAILED:")
+    for error in graph_validation["errors"]:
+        print(f"   ERROR: {error}")
+    print("\n⚠️ Must fix graph structure before finalizing agent")
+    # Ask user how to proceed
+
+# Additional validation: Check entry_points format
+if not isinstance(entry_points, dict):
+    print("❌ CRITICAL ERROR: entry_points must be a dict")
+    print(f"   Current value: {entry_points} (type: {type(entry_points)})")
+    print("   Correct format: {'start': 'node-id'}")
+    # STOP - This is the mistake that caused the support_ticket_agent bug
+
+if entry_points.get("start") != entry_node_id:
+    print("❌ CRITICAL ERROR: entry_points['start'] must match entry_node")
+    print(f"   entry_points: {entry_points}")
+    print(f"   entry_node: {entry_node_id}")
+    print("   They must be consistent!")
 ```
 
+**CRITICAL:** Do NOT proceed to Step 5 (finalization) until graph validation passes. This checkpoint prevents structural bugs from reaching production.
+
 ### Step 5: Finalize Agent Class
 
+**Pre-flight checks before finalization:**
+
+```python
+# MANDATORY: Verify all validations passed before finalizing
+print("\n🔍 Pre-finalization Checklist:")
+
+# Get current session status
+status = json.loads(mcp__agent-builder__get_session_status())
+
+checks_passed = True
+
+# Check 1: Goal defined
+if not status["has_goal"]:
+    print("❌ No goal defined")
+    checks_passed = False
+else:
+    print(f"✅ Goal defined: {status['goal_name']}")
+
+# Check 2: Nodes added
+if status["node_count"] == 0:
+    print("❌ No nodes added")
+    checks_passed = False
+else:
+    print(f"✅ {status['node_count']} nodes added: {', '.join(status['nodes'])}")
+
+# Check 3: Edges added
+if status["edge_count"] == 0:
+    print("❌ No edges added")
+    checks_passed = False
+else:
+    print(f"✅ {status['edge_count']} edges added")
+
+# Check 4: Entry points format correct
+if not isinstance(entry_points, dict) or "start" not in entry_points:
+    print("❌ CRITICAL: entry_points format incorrect")
+    print(f"   Current: {entry_points}")
+    print("   Required: {'start': 'node-id'}")
+    checks_passed = False
+else:
+    print(f"✅ Entry points valid: {entry_points}")
+
+if not checks_passed:
+    print("\n⚠️ CANNOT PROCEED to finalization until all checks pass")
+    print("   Fix the issues above first")
+    # Ask user how to proceed or stop here
+    return
+
+print("\n✅ All pre-flight checks passed - proceeding to finalization\n")
+```
+
 Write the agent class:
 
 ````python
@@ -530,7 +769,7 @@ content=readme_content
 ```
 
 ✅ Agent class written to agent.py
-✅ Package exports finalized in **init**.py
+✅ Package exports finalized in __init__.py
 ✅ README.md generated
 
 🎉 Agent complete: exports/technical_research_agent/
@@ -539,7 +778,23 @@ Commands:
 python -m technical_research_agent info
 python -m technical_research_agent validate
 python -m technical_research_agent run --input '{"topic": "..."}'
+```
 
+**Final session summary:**
+
+```python
+# Show final MCP session status
+status = json.loads(mcp__agent-builder__get_session_status())
+
+print("\n📊 Build Session Summary:")
+print(f"   Session ID: {status['session_id']}")
+print(f"   Agent: {status['name']}")
+print(f"   Goal: {status['goal_name']}")
+print(f"   Nodes: {status['node_count']}")
+print(f"   Edges: {status['edge_count']}")
+print(f"   MCP Servers: {status['mcp_servers_count']}")
+print("\n✅ Agent construction complete with full validation")
+print(f"\nSession saved to: ~/.claude-code-agent-builder/sessions/{status['session_id']}.json")
 ````
 
 ## CLI Template

ENVIRONMENT_SETUP.md

@@ -0,0 +1,347 @@
+# Agent Development Environment Setup
+
+Complete setup guide for building and running goal-driven agents with the Hive framework.
+
+## Quick Setup
+
+```bash
+# Run the automated setup script
+./scripts/setup-python.sh
+```
+
+This will:
+
+- Check Python version (requires 3.10+, recommends 3.11+)
+- Install the core framework package (`framework`)
+- Install the tools package (`aden_tools`)
+- Fix package compatibility issues (openai + litellm)
+- Verify all installations
+
+## Manual Setup (Alternative)
+
+If you prefer to set up manually or the script fails:
+
+### 1. Install Core Framework
+
+```bash
+cd core
+pip install -e .
+```
+
+### 2. Install Tools Package
+
+```bash
+cd tools
+pip install -e .
+```
+
+### 3. Upgrade OpenAI Package
+
+```bash
+# litellm requires openai >= 1.0.0
+pip install --upgrade "openai>=1.0.0"
+```
+
+### 4. Verify Installation
+
+```bash
+python -c "import framework; print('✓ framework OK')"
+python -c "import aden_tools; print('✓ aden_tools OK')"
+python -c "import litellm; print('✓ litellm OK')"
+```
+
+## Requirements
+
+### Python Version
+
+- **Minimum:** Python 3.10
+- **Recommended:** Python 3.11 or 3.12
+- **Tested on:** Python 3.11, 3.12, 3.13
+
+### System Requirements
+
+- pip (latest version)
+- 2GB+ RAM
+- Internet connection (for LLM API calls)
+
+### API Keys (Optional)
+
+For running agents with real LLMs:
+
+```bash
+export ANTHROPIC_API_KEY="your-key-here"
+```
+
+## Running Agents
+
+All agent commands must be run from the project root with `PYTHONPATH` set:
+
+```bash
+# From /home/timothy/oss/hive/ directory
+PYTHONPATH=core:exports python -m agent_name COMMAND
+```
+
+### Example: Support Ticket Agent
+
+```bash
+# Validate agent structure
+PYTHONPATH=core:exports python -m support_ticket_agent validate
+
+# Show agent information
+PYTHONPATH=core:exports python -m support_ticket_agent info
+
+# Run agent with input
+PYTHONPATH=core:exports python -m support_ticket_agent run --input '{
+  "ticket_content": "My login is broken. Error 401.",
+  "customer_id": "CUST-123",
+  "ticket_id": "TKT-456"
+}'
+
+# Run in mock mode (no LLM calls)
+PYTHONPATH=core:exports python -m support_ticket_agent run --mock --input '{...}'
+```
+
+### Example: Other Agents
+
+```bash
+# Market Research Agent
+PYTHONPATH=core:exports python -m market_research_agent info
+
+# Outbound Sales Agent
+PYTHONPATH=core:exports python -m outbound_sales_agent validate
+
+# Personal Assistant Agent
+PYTHONPATH=core:exports python -m personal_assistant_agent run --input '{...}'
+```
+
+## Building New Agents
+
+Use Claude Code CLI with the agent building skills:
+
+### 1. Install Skills (One-time)
+
+```bash
+./quickstart.sh
+```
+
+This installs:
+
+- `/building-agents` - Build new agents
+- `/testing-agent` - Test agents
+
+### 2. Build an Agent
+
+```
+claude> /building-agents
+```
+
+Follow the prompts to:
+
+1. Define your agent's goal
+2. Design the workflow nodes
+3. Connect edges
+4. Generate the agent package
+
+### 3. Test Your Agent
+
+```
+claude> /testing-agent
+```
+
+Creates comprehensive test suites for your agent.
+
+## Troubleshooting
+
+### "ModuleNotFoundError: No module named 'framework'"
+
+**Solution:** Install the core package:
+
+```bash
+cd core && pip install -e .
+```
+
+### "ModuleNotFoundError: No module named 'aden_tools'"
+
+**Solution:** Install the tools package:
+
+```bash
+cd tools && pip install -e .
+```
+
+Or run the setup script:
+
+```bash
+./scripts/setup-python.sh
+```
+
+### "ModuleNotFoundError: No module named 'openai.\_models'"
+
+**Cause:** Outdated `openai` package (0.27.x) incompatible with `litellm`
+
+**Solution:** Upgrade openai:
+
+```bash
+pip install --upgrade "openai>=1.0.0"
+```
+
+### "No module named 'support_ticket_agent'"
+
+**Cause:** Not running from project root or missing PYTHONPATH
+
+**Solution:** Ensure you're in `/home/timothy/oss/hive/` and use:
+
+```bash
+PYTHONPATH=core:exports python -m support_ticket_agent validate
+```
+
+### Agent imports fail with "broken installation"
+
+**Symptom:** `pip list` shows packages pointing to non-existent directories
+
+**Solution:** Reinstall packages properly:
+
+```bash
+# Remove broken installations
+pip uninstall -y framework tools aden-tools
+
+# Reinstall correctly
+cd /home/timothy/oss/hive
+./scripts/setup-python.sh
+```
+
+## Package Structure
+
+The Hive framework consists of three Python packages:
+
+```
+hive/
+├── core/                    # Core framework (runtime, graph executor, LLM providers)
+│   ├── framework/
+│   ├── pyproject.toml
+│   └── requirements.txt
+│
+├── tools/                   # Tools and MCP servers
+│   ├── src/
+│   │   └── aden_tools/     # Actual package location
+│   ├── pyproject.toml
+│   └── README.md
+│
+└── exports/                 # Agent packages (your agents go here)
+    ├── support_ticket_agent/
+    ├── market_research_agent/
+    ├── outbound_sales_agent/
+    └── personal_assistant_agent/
+```
+
+### Why PYTHONPATH is Required
+
+The packages are installed in **editable mode** (`pip install -e`), which means:
+
+- `framework` and `aden_tools` are globally importable (no PYTHONPATH needed)
+- `exports` is NOT installed as a package (PYTHONPATH required)
+
+This design allows agents in `exports/` to be:
+
+- Developed independently
+- Version controlled separately
+- Deployed as standalone packages
+
+## Development Workflow
+
+### 1. Setup (Once)
+
+```bash
+./scripts/setup-python.sh
+```
+
+### 2. Build Agent (Claude Code)
+
+```
+claude> /building-agents
+Enter goal: "Build an agent that processes customer support tickets"
+```
+
+### 3. Validate Agent
+
+```bash
+PYTHONPATH=core:exports python -m support_ticket_agent validate
+```
+
+### 4. Test Agent
+
+```
+claude> /testing-agent
+```
+
+### 5. Run Agent
+
+```bash
+PYTHONPATH=core:exports python -m support_ticket_agent run --input '{...}'
+```
+
+## IDE Setup
+
+### VSCode
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}/core",
+    "${workspaceFolder}/exports"
+  ],
+  "python.autoComplete.extraPaths": [
+    "${workspaceFolder}/core",
+    "${workspaceFolder}/exports"
+  ]
+}
+```
+
+### PyCharm
+
+1. Open Project Settings → Project Structure
+2. Mark `core` as Sources Root
+3. Mark `exports` as Sources Root
+
+## Environment Variables
+
+### Required for LLM Operations
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### Optional Configuration
+
+```bash
+# Credentials storage location (default: ~/.aden/credentials)
+export ADEN_CREDENTIALS_PATH="/custom/path"
+
+# Agent storage location (default: /tmp)
+export AGENT_STORAGE_PATH="/custom/storage"
+```
+
+## Additional Resources
+
+- **Framework Documentation:** [core/README.md](core/README.md)
+- **Tools Documentation:** [tools/README.md](tools/README.md)
+- **Example Agents:** [exports/](exports/)
+- **Agent Building Guide:** [.claude/skills/building-agents-construction/SKILL.md](.claude/skills/building-agents-construction/SKILL.md)
+- **Testing Guide:** [.claude/skills/testing-agent/SKILL.md](.claude/skills/testing-agent/SKILL.md)
+
+## Contributing
+
+When contributing agent packages:
+
+1. Place agents in `exports/agent_name/`
+2. Follow the standard agent structure (see existing agents)
+3. Include README.md with usage instructions
+4. Add tests if using `/testing-agent`
+5. Document required environment variables
+
+## Support
+
+- **Issues:** https://github.com/adenhq/hive/issues
+- **Discord:** https://discord.com/invite/MXE49hrKDk
+- **Documentation:** https://docs.adenhq.com/

README.md

@@ -88,6 +88,20 @@ docker compose up
 - API: http://localhost:4000
 - Health: http://localhost:4000/health
 
+### Python Agent Development
+
+For building and running goal-driven agents:
+
+```bash
+# One-time setup
+./scripts/setup-python.sh
+
+# Build and test agents
+# See ENVIRONMENT_SETUP.md for complete guide
+```
+
+**[📖 Python Setup Guide](ENVIRONMENT_SETUP.md)** - Complete instructions for agent development
+
 ## Features
 
 - **Goal-Driven Development** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them

scripts/setup-python.sh

@@ -0,0 +1,206 @@
+#!/bin/bash
+#
+# setup-python.sh - Python Environment Setup for Hive Agent Framework
+#
+# This script sets up the Python environment with all required packages
+# for building and running goal-driven agents.
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+echo ""
+echo "=================================================="
+echo "  Hive Agent Framework - Python Setup"
+echo "=================================================="
+echo ""
+
+# Check for Python
+if ! command -v python &> /dev/null && ! command -v python3 &> /dev/null; then
+    echo -e "${RED}Error: Python is not installed.${NC}"
+    echo "Please install Python 3.11+ from https://python.org"
+    exit 1
+fi
+
+# Use python3 if available, otherwise python
+PYTHON_CMD="python3"
+if ! command -v python3 &> /dev/null; then
+    PYTHON_CMD="python"
+fi
+
+# Check Python version
+PYTHON_VERSION=$($PYTHON_CMD -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+PYTHON_MAJOR=$($PYTHON_CMD -c 'import sys; print(sys.version_info.major)')
+PYTHON_MINOR=$($PYTHON_CMD -c 'import sys; print(sys.version_info.minor)')
+
+echo -e "${BLUE}Detected Python:${NC} $PYTHON_VERSION"
+
+if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 10 ]); then
+    echo -e "${RED}Error: Python 3.10+ is required (found $PYTHON_VERSION)${NC}"
+    echo "Please upgrade your Python installation"
+    exit 1
+fi
+
+if [ "$PYTHON_MINOR" -lt 11 ]; then
+    echo -e "${YELLOW}Warning: Python 3.11+ is recommended for best compatibility${NC}"
+    echo -e "${YELLOW}You have Python $PYTHON_VERSION which may work but is not officially supported${NC}"
+    echo ""
+fi
+
+echo -e "${GREEN}✓${NC} Python version check passed"
+echo ""
+
+# Check for pip
+if ! $PYTHON_CMD -m pip --version &> /dev/null; then
+    echo -e "${RED}Error: pip is not installed${NC}"
+    echo "Please install pip for Python $PYTHON_VERSION"
+    exit 1
+fi
+
+echo -e "${GREEN}✓${NC} pip detected"
+echo ""
+
+# Upgrade pip, setuptools, and wheel
+echo "Upgrading pip, setuptools, and wheel..."
+$PYTHON_CMD -m pip install --upgrade pip setuptools wheel > /dev/null 2>&1
+echo -e "${GREEN}✓${NC} Core packages upgraded"
+echo ""
+
+# Install core framework package
+echo "=================================================="
+echo "Installing Core Framework Package"
+echo "=================================================="
+echo ""
+cd "$PROJECT_ROOT/core"
+
+if [ -f "pyproject.toml" ]; then
+    echo "Installing framework from core/ (editable mode)..."
+    $PYTHON_CMD -m pip install -e . > /dev/null 2>&1
+    if [ $? -eq 0 ]; then
+        echo -e "${GREEN}✓${NC} Framework package installed"
+    else
+        echo -e "${YELLOW}⚠${NC} Framework installation encountered issues (may be OK if already installed)"
+    fi
+else
+    echo -e "${YELLOW}⚠${NC} No pyproject.toml found in core/, skipping framework installation"
+fi
+echo ""
+
+# Install tools package
+echo "=================================================="
+echo "Installing Tools Package (aden_tools)"
+echo "=================================================="
+echo ""
+cd "$PROJECT_ROOT/tools"
+
+if [ -f "pyproject.toml" ]; then
+    echo "Installing aden_tools from tools/ (editable mode)..."
+    $PYTHON_CMD -m pip install -e . > /dev/null 2>&1
+    if [ $? -eq 0 ]; then
+        echo -e "${GREEN}✓${NC} Tools package installed"
+    else
+        echo -e "${RED}✗${NC} Tools installation failed"
+        exit 1
+    fi
+else
+    echo -e "${RED}Error: No pyproject.toml found in tools/${NC}"
+    exit 1
+fi
+echo ""
+
+# Fix openai version compatibility with litellm
+echo "=================================================="
+echo "Fixing Package Compatibility"
+echo "=================================================="
+echo ""
+
+# Check openai version
+OPENAI_VERSION=$($PYTHON_CMD -c "import openai; print(openai.__version__)" 2>/dev/null || echo "not_installed")
+
+if [ "$OPENAI_VERSION" = "not_installed" ]; then
+    echo "Installing openai package..."
+    $PYTHON_CMD -m pip install "openai>=1.0.0" > /dev/null 2>&1
+    echo -e "${GREEN}✓${NC} openai package installed"
+elif [[ "$OPENAI_VERSION" =~ ^0\. ]]; then
+    echo -e "${YELLOW}Found old openai version: $OPENAI_VERSION${NC}"
+    echo "Upgrading to openai 1.x+ for litellm compatibility..."
+    $PYTHON_CMD -m pip install --upgrade "openai>=1.0.0" > /dev/null 2>&1
+    OPENAI_VERSION=$($PYTHON_CMD -c "import openai; print(openai.__version__)" 2>/dev/null)
+    echo -e "${GREEN}✓${NC} openai upgraded to $OPENAI_VERSION"
+else
+    echo -e "${GREEN}✓${NC} openai $OPENAI_VERSION is compatible"
+fi
+echo ""
+
+# Verify installations
+echo "=================================================="
+echo "Verifying Installation"
+echo "=================================================="
+echo ""
+
+cd "$PROJECT_ROOT"
+
+# Test framework import
+if $PYTHON_CMD -c "import framework; print('framework OK')" > /dev/null 2>&1; then
+    echo -e "${GREEN}✓${NC} framework package imports successfully"
+else
+    echo -e "${RED}✗${NC} framework package import failed"
+    echo -e "${YELLOW}  Note: This may be OK if you don't need the framework${NC}"
+fi
+
+# Test aden_tools import
+if $PYTHON_CMD -c "import aden_tools; print('aden_tools OK')" > /dev/null 2>&1; then
+    echo -e "${GREEN}✓${NC} aden_tools package imports successfully"
+else
+    echo -e "${RED}✗${NC} aden_tools package import failed"
+    exit 1
+fi
+
+# Test litellm + openai compatibility
+if $PYTHON_CMD -c "import litellm; print('litellm OK')" > /dev/null 2>&1; then
+    echo -e "${GREEN}✓${NC} litellm package imports successfully"
+else
+    echo -e "${YELLOW}⚠${NC} litellm import had issues (may be OK if not using LLM features)"
+fi
+
+echo ""
+
+# Print agent commands
+echo "=================================================="
+echo "  Setup Complete!"
+echo "=================================================="
+echo ""
+echo "Python packages installed:"
+echo "  • framework (core agent runtime)"
+echo "  • aden_tools (tools and MCP servers)"
+echo "  • All dependencies and compatibility fixes applied"
+echo ""
+echo "To run agents, use:"
+echo ""
+echo "  ${BLUE}# From project root:${NC}"
+echo "  PYTHONPATH=core:exports python -m agent_name validate"
+echo "  PYTHONPATH=core:exports python -m agent_name info"
+echo "  PYTHONPATH=core:exports python -m agent_name run --input '{...}'"
+echo ""
+echo "Available commands for your new agent:"
+echo "  PYTHONPATH=core:exports python -m support_ticket_agent validate"
+echo "  PYTHONPATH=core:exports python -m support_ticket_agent info"
+echo "  PYTHONPATH=core:exports python -m support_ticket_agent run --input '{\"ticket_content\":\"...\",\"customer_id\":\"...\",\"ticket_id\":\"...\"}'"
+echo ""
+echo "To build new agents, use Claude Code skills:"
+echo "  • /building-agents - Build a new agent"
+echo "  • /testing-agent   - Test an existing agent"
+echo ""
+echo "Documentation: ${PROJECT_ROOT}/README.md"
+echo "Agent Examples: ${PROJECT_ROOT}/exports/"
+echo ""