Metadata-Version: 2.3
Name: agentmap
Version: 0.3.0
Summary: AgentMap: Build and deploy LangGraph workflows from CSV files for fun and profit!
License: MIT
Keywords: ai,agents,workflows,langgraph,csv,automation
Author: John Welborn
Author-email: jwwelbor@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: llm
Provides-Extra: storage
Requires-Dist: dependency_injector (>=4.41.0)
Requires-Dist: dill (>=0.3.6)
Requires-Dist: fastapi (>=0.111.0)
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: langchain (>=0.1.0)
Requires-Dist: langchain-anthropic (>=0.3.13,<0.4.0) ; extra == "llm" or extra == "all"
Requires-Dist: langchain-community (>=0.3.23)
Requires-Dist: langchain-core (>=0.1.0)
Requires-Dist: langchain-openai (>=0.3.17) ; extra == "llm" or extra == "all"
Requires-Dist: langgraph (>=0.4.1)
Requires-Dist: packaging
Requires-Dist: pandas (>=2.2.1)
Requires-Dist: pydantic (>=2.6.3)
Requires-Dist: python-multipart (>=0.0.9)
Requires-Dist: pyyaml
Requires-Dist: typer (>=0.12.3)
Project-URL: Bug Tracker, https://github.com/jwwelbor/AgentMap/issues
Project-URL: Changelog, https://github.com/jwwelbor/AgentMap/blob/main/CHANGELOG.md
Project-URL: Documentation, https://jwwelbor.github.io/AgentMap
Project-URL: Homepage, https://jwwelbor.github.io/AgentMap
Project-URL: Repository, https://github.com/jwwelbor/AgentMap
Description-Content-Type: text/markdown

# AgentMap

**Build and deploy LangGraph workflows from CSV files for fun and profit!**

AgentMap is a declarative orchestration framework that transforms simple CSV files into powerful AI agent workflows. Define complex multi-agent systems, conversational interfaces, and document processing pipelines without writing extensive code.

[![PyPI version](https://badge.fury.io/py/agentmap.svg)](https://badge.fury.io/py/agentmap)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 Why AgentMap?

**Traditional Approach** - Complex code for simple workflows:
```python
# Hundreds of lines of LangGraph setup code
from langgraph import StateGraph
from langchain_openai import ChatOpenAI
# ... extensive boilerplate ...
```

**AgentMap Approach** - Simple CSV for complex workflows:
```csv
GraphName,Node,AgentType,Input_Fields,Output_Field,Prompt,Success_Next
ChatBot,GetInput,input,,user_input,How can I help you?,Respond
ChatBot,Respond,openai,user_input|memory,response,You are a helpful assistant: {user_input},GetInput
```

## 🚀 Key Features

### 🎯 **Declarative Workflow Definition**
- **CSV-Driven**: Define entire workflows in simple spreadsheets
- **Visual Design**: Easy to understand and modify workflow structure  
- **Version Control**: Track changes with standard Git workflows

### 🤖 **Rich Agent Ecosystem**
- **20+ Built-in Agents**: LLM providers, storage systems, utilities
- **Custom Agent Support**: Scaffold and integrate your own agents
- **Intelligent Orchestration**: Dynamic routing based on content analysis

### 🧠 **Advanced AI Capabilities**
- **Memory Management**: Conversational agents with context retention
- **Multi-LLM Support**: OpenAI, Claude, Gemini with unified interface
- **Vector Databases**: Semantic search and document retrieval
- **Prompt Management**: Centralized prompt organization and versioning

### 💾 **Universal Storage Integration**
- **Local Storage**: CSV, JSON, file operations
- **Cloud Storage**: Azure Blob, AWS S3, Google Cloud Storage
- **Databases**: Firebase, vector stores (Chroma, FAISS)
- **Document Processing**: PDF, Word, Markdown with LangChain integration

### 🛠️ **Developer Experience**
- **Powerful CLI**: Run, scaffold, compile, and export workflows
- **Auto-scaffolding**: Generate starter code for custom components
- **Execution Tracking**: Detailed monitoring with configurable success policies
- **Hot Reloading**: Rapid development and testing cycles

## 📦 Installation

### Base Installation
```bash
pip install agentmap
```

### Feature-Specific Installation
```bash
# LLM providers (OpenAI, Claude, Gemini)
pip install "agentmap[llm]"

# Storage integrations (Firebase, cloud, vector DBs)
pip install "agentmap[storage]"

# Everything included
pip install "agentmap[all]"
```

### Development Installation
```bash
# Clone and install for development
git clone https://github.com/jwwelbor/AgentMap.git
cd AgentMap
pip install -e ".[all]"
```

## ⚡ Quick Start

### 1. Create Your First Workflow

Create `hello_world.csv`:
```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
HelloWorld,Start,,Starting node,echo,Process,,input,initial_data,
HelloWorld,Process,,Process the greeting,openai,End,,initial_data,processed_greeting,"Make this greeting more enthusiastic: {initial_data}"
HelloWorld,End,,Final response,echo,,,processed_greeting,final_output,
```

### 2. Run the Workflow

**Via Python:**
```python
from agentmap.runner import run_graph

result = run_graph(
    graph_name="HelloWorld",
    initial_state={"input": "Hello, AgentMap!"},
    csv_path="hello_world.csv"
)

print(f"Result: {result['final_output']}")
print(f"Processing time: {result.get('total_duration', 0):.2f}s")
```

**Via CLI:**
```bash
agentmap run --graph HelloWorld --csv hello_world.csv --state '{"input": "Hello, AgentMap!"}'
```

### 3. Examine Execution Flow
```python
# View detailed execution path
for step in result.get("execution_steps", []):
    status = "✅" if step["success"] else "❌"
    print(f"{status} {step['node']} ({step['duration']:.3f}s)")
```

## 📋 CSV Schema Reference

AgentMap workflows are defined using CSV files with the following columns:

| Column | Required | Description | Examples |
|--------|----------|-------------|----------|
| `GraphName` | ✅ | Workflow identifier | `ChatBot`, `DocumentProcessor` |
| `Node` | ✅ | Unique node name within graph | `GetInput`, `ProcessData`, `SaveResults` |
| `Edge` | ❌ | Direct connection to next node | `NextNode`, `func:custom_router` |
| `Context` | ❌ | Node configuration (JSON or text) | `{"memory_key":"chat_history"}` |
| `AgentType` | ❌ | Type of agent to use | `openai`, `claude`, `csv_reader` |
| `Success_Next` | ❌ | Next node on success | `ProcessData`, `Success\|Backup` |
| `Failure_Next` | ❌ | Next node on failure | `ErrorHandler`, `Retry` |
| `Input_Fields` | ❌ | State fields to extract as input | `user_input\|context\|memory` |
| `Output_Field` | ❌ | Field to store agent output | `response`, `processed_data` |
| `Prompt` | ❌ | Agent prompt or configuration | `"You are helpful: {input}"`, `prompt:system_instructions` |
| `Description` | ❌ | Documentation for the node | `"Validates user input format"` |

### Advanced Routing Patterns

**Conditional Branching:**
```csv
GraphName,Node,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field
DataFlow,Validate,branching,Transform,ErrorHandler,raw_data,validation_result
```

**Multiple Targets:**
```csv
GraphName,Node,AgentType,Success_Next,Input_Fields,Output_Field
Parallel,Distribute,default,ProcessA|ProcessB|ProcessC,data,distributed_tasks
```

**Function-Based Routing:**
```csv
GraphName,Node,Edge,AgentType,Input_Fields,Output_Field
Smart,Classifier,func:choose_specialist,default,user_query,classification
```

## 🤖 Agent Types Reference

### Core Agents

| Agent Type | Purpose | Input Behavior | Output Behavior |
|------------|---------|----------------|-----------------|
| `default` | Basic processing | Any fields | Returns message with prompt |
| `echo` | Pass-through | First input field | Returns input unchanged |
| `input` | User interaction | Ignored | Prompts user, returns input |
| `branching` | Conditional routing | Looks for success indicators | Returns routing decision |
| `success` | Always succeeds | Any | Returns success message |
| `failure` | Always fails | Any | Returns failure message |

**Example:**
```csv
TestFlow,GetData,input,,user_input,Enter your name:,ValidateData
TestFlow,ValidateData,branching,ProcessData,ErrorHandler,user_input,validation_result
TestFlow,ProcessData,default,End,,user_input,processed_result,"Processing: {user_input}"
```

### LLM Agents

| Agent Type | Provider | Features | Configuration |
|------------|----------|----------|---------------|
| `openai` (aliases: `gpt`, `chatgpt`) | OpenAI | GPT models, memory | Model, temperature, memory settings |
| `claude` (alias: `anthropic`) | Anthropic | Claude models, memory | Model, temperature, memory settings |  
| `gemini` (alias: `google`) | Google | Gemini models, memory | Model, temperature, memory settings |

**Memory-Enabled Conversation:**
```csv
ChatBot,GetInput,input,,user_message,What can I help with?,Respond
ChatBot,Respond,openai,user_message|chat_memory,response,"You are helpful. Human: {user_message}",GetInput
```

**Context Configuration:**
```csv
GraphName,Node,Context,AgentType,Input_Fields,Output_Field,Prompt
Advanced,Analyze,"{\"memory_key\":\"analysis_history\",\"max_memory_messages\":10,\"model\":\"gpt-4\",\"temperature\":0.2}",openai,data|analysis_history,insights,"Analyze this data: {data}"
```

### Storage Agents

#### File Operations
| Agent Type | Purpose | Required Input | Output |
|------------|---------|----------------|--------|
| `file_reader` | Read documents | `collection` (file path) | Document content with metadata |
| `file_writer` | Write files | `collection` (path), `data` | Operation result |

**Document Processing Example:**
```csv
DocFlow,ReadDoc,"{\"should_split\":true,\"chunk_size\":1000}",file_reader,collection,documents,
DocFlow,Summarize,openai,documents,summary,"Summarize these documents: {documents}",SaveSummary
DocFlow,SaveSummary,file_writer,summary,result,output/summary.md
```

#### Structured Data
| Agent Type | Purpose | Required Input | Output |
|------------|---------|----------------|--------|
| `csv_reader` | Read CSV files | `collection` (file path) | Parsed CSV data |
| `csv_writer` | Write CSV files | `collection` (path), `data` | Operation result |
| `json_reader` | Read JSON files | `collection` (file path) | JSON data |
| `json_writer` | Write JSON files | `collection` (path), `data` | Operation result |

#### Cloud Storage
| Agent Type | Purpose | URI Format | Authentication |
|------------|---------|------------|----------------|
| `cloud_json_reader` | Read from cloud | `azure://container/file.json` | Connection string/keys |
| `cloud_json_writer` | Write to cloud | `s3://bucket/file.json` | AWS credentials |

**Cloud Storage Example:**
```csv
CloudFlow,LoadData,cloud_json_reader,collection,data,"azure://documents/input.json"
CloudFlow,SaveResults,cloud_json_writer,processed_data,result,"s3://output/results.json"
```

#### Vector Databases
| Agent Type | Purpose | Configuration | Use Cases |
|------------|---------|---------------|-----------|
| `vector_reader` | Similarity search | Store configuration | Document retrieval, semantic search |
| `vector_writer` | Store embeddings | Store configuration | Knowledge base building |

**Vector Search Example:**
```csv
SearchFlow,LoadDocs,vector_writer,documents,load_result,
SearchFlow,Search,vector_reader,query,search_results,
SearchFlow,Answer,openai,search_results|query,response,"Answer based on: {search_results}. Question: {query}"
```

### Orchestration Agent

The `orchestrator` agent provides intelligent, dynamic routing based on content analysis:

**Basic Orchestration:**
```csv
RouterFlow,MainRouter,orchestrator,available_nodes|user_input,next_node,"Route user request to appropriate handler"
RouterFlow,ProductInfo,openai,user_input,response,"I handle product information requests"
RouterFlow,TechSupport,openai,user_input,response,"I handle technical support questions"
RouterFlow,OrderStatus,openai,user_input,response,"I handle order status inquiries"
```

**Advanced Configuration:**
```csv
GraphName,Node,Context,AgentType,Input_Fields,Output_Field,Prompt
SmartRouter,MainRouter,"{\"matching_strategy\":\"tiered\",\"confidence_threshold\":0.8,\"node_filter\":\"ProductInfo|TechSupport\"}",orchestrator,available_nodes|user_input,next_node,"Intelligently route user queries"
```

## 🧠 Advanced Features

### Memory Management

AgentMap supports conversational memory for LLM agents:

**Configuration Options:**
- `memory_key`: State field for memory storage (default: "memory")
- `max_memory_messages`: Maximum conversation history (default: unlimited)

**Multi-Turn Conversation:**
```csv
Interview,Welcome,default,,welcome_message,"Welcome to the interview!",AskQuestion
Interview,AskQuestion,"{\"memory_key\":\"interview_history\",\"max_memory_messages\":8}",claude,question_number|interview_history,current_question,"Ask interview question #{question_number}"
Interview,GetAnswer,input,current_question,user_answer,,EvaluateAnswer
Interview,EvaluateAnswer,"{\"memory_key\":\"interview_history\"}",claude,user_answer|interview_history,evaluation,"Evaluate this answer: {user_answer}"
```

**Memory State Evolution:**
```python
# Initial state
{"user_input": "Hello, how are you?"}

# After first response
{
    "user_input": "Hello, how are you?",
    "response": "I'm well, thanks for asking!",
    "memory": [
        {"role": "user", "content": "Hello, how are you?"},
        {"role": "assistant", "content": "I'm well, thanks for asking!"}
    ]
}

# After second interaction
{
    "user_input": "Tell me about AI",
    "response": "AI is fascinating! Given our conversation...",
    "memory": [
        {"role": "user", "content": "Hello, how are you?"},
        {"role": "assistant", "content": "I'm well, thanks for asking!"},
        {"role": "user", "content": "Tell me about AI"},
        {"role": "assistant", "content": "AI is fascinating! Given our conversation..."}
    ]
}
```

### Execution Tracking

AgentMap provides comprehensive execution tracking with configurable success policies:

**Configuration in `agentmap_config.yaml`:**
```yaml
execution:
  tracking:
    enabled: true              # Enable detailed tracking
    track_outputs: false       # Record output values
    track_inputs: false        # Record input values
  
  success_policy:
    type: "critical_nodes"     # Policy type
    critical_nodes:            # Critical nodes for success
      - "ValidateInput"
      - "ProcessPayment"
      - "SendConfirmation"
```

**Available Success Policies:**
- `all_nodes`: All executed nodes must succeed (default)
- `final_node`: Only the final node must succeed
- `critical_nodes`: All specified critical nodes must succeed
- `custom`: Use custom policy function

**Accessing Execution Data:**
```python
result = run_graph("PaymentFlow", initial_state)

# Policy-based success (always available)
if result["graph_success"]:
    print("Workflow succeeded according to policy!")

# Detailed execution summary (when detailed tracking enabled)
summary = result["__execution_summary"]
print(f"Total duration: {summary['total_duration']:.2f}s")
print(f"Execution path: {' → '.join(summary['execution_path'])}")

# Find failing nodes
failed_nodes = [
    node for node, data in summary["node_results"].items() 
    if not data["success"]
]
```

### Cloud Storage Integration

AgentMap seamlessly integrates with major cloud storage providers:

**Storage Configuration (`storage_config.yaml`):**
```yaml
json:
  default_provider: "local"
  providers:
    azure:
      connection_string: "env:AZURE_STORAGE_CONNECTION_STRING"
      default_container: "documents"
      containers:
        users: "users-container"
        reports: "reports-container"
    
    aws:
      region: "us-west-2"
      access_key: "env:AWS_ACCESS_KEY_ID"
      secret_key: "env:AWS_SECRET_ACCESS_KEY"
      default_bucket: "my-documents"
    
    gcp:
      project_id: "env:GCP_PROJECT_ID"
      credentials_file: "path/to/service-account.json"
      default_bucket: "documents"
```

**URI Formats:**
- Azure: `azure://container/path/file.json`
- AWS S3: `s3://bucket/path/file.json`  
- GCP: `gs://bucket/path/file.json`

### Prompt Management

Centralized prompt management with multiple reference types:

**Registry Prompts (`prompts/registry.yaml`):**
```yaml
system_instructions: "You are a helpful AI assistant..."
customer_service: "You are a customer service representative..."
data_analyst: "You are a data analyst. Analyze the following data..."
```

**Usage in CSV:**
```csv
GraphName,Node,AgentType,Input_Fields,Output_Field,Prompt
Analysis,Analyze,openai,data,insights,prompt:data_analyst
Support,Respond,claude,user_query,response,prompt:customer_service
```

**File-Based Prompts:**
```csv
GraphName,Node,AgentType,Prompt
Complex,LongAnalysis,openai,file:prompts/detailed_analysis.txt
```

**YAML Key References:**
```csv
GraphName,Node,AgentType,Prompt
Multi,Specialized,claude,yaml:prompts/specialists.yaml#technical_support
```

## 🔧 Configuration

### Main Configuration (`agentmap_config.yaml`)

```yaml
# Default CSV file path
csv_path: "workflows/default.csv"

# Auto-compilation setting
autocompile: false

# Directory paths
paths:
  custom_agents: "agentmap/agents/custom"
  functions: "agentmap/functions"

# LLM provider settings
llm:
  openai:
    api_key: "env:OPENAI_API_KEY"
    model: "gpt-3.5-turbo"
    temperature: 0.7
  
  anthropic:
    api_key: "env:ANTHROPIC_API_KEY"
    model: "claude-3-sonnet-20240229"
    temperature: 0.7
  
  google:
    api_key: "env:GOOGLE_API_KEY"
    model: "gemini-pro"

# Prompt management
prompts:
  directory: "prompts"
  registry_file: "prompts/registry.yaml"
  enable_cache: true

# Execution tracking
execution:
  tracking:
    enabled: false
    track_outputs: false
    track_inputs: false
  success_policy:
    type: "all_nodes"
```

### Environment Variables

```bash
# LLM Provider Keys
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GOOGLE_API_KEY="your-google-key"

# Cloud Storage
export AZURE_STORAGE_CONNECTION_STRING="your-connection-string"
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export GCP_PROJECT_ID="your-project-id"

# AgentMap Settings
export AGENTMAP_CONFIG_PATH="custom_config.yaml"
export AGENTMAP_CSV_PATH="workflows/main.csv"
```

## 💡 Practical Examples

### Simple Linear Workflow

**Use Case:** Basic data processing pipeline

```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
DataPipeline,LoadData,,Load CSV data,csv_reader,ValidateData,HandleError,collection,raw_data
DataPipeline,ValidateData,,Validate data format,branching,TransformData,HandleError,raw_data,validation_result
DataPipeline,TransformData,,Transform data,default,SaveResults,HandleError,raw_data,processed_data,"Clean and transform data"
DataPipeline,SaveResults,,Save processed data,csv_writer,End,HandleError,processed_data,save_result
DataPipeline,End,,Pipeline complete,echo,,,save_result,final_message
DataPipeline,HandleError,,Handle any errors,echo,End,,error,error_message
```

**Usage:**
```python
result = run_graph(
    "DataPipeline", 
    {"collection": "data/raw_sales.csv"}
)
```

### Conversational AI Assistant

**Use Case:** Multi-turn customer service bot

```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
CustomerBot,Welcome,,Welcome message,default,GetQuery,,user,welcome_message,"Welcome! How can I help you today?",GetQuery
CustomerBot,GetQuery,,Get user query,input,ClassifyIntent,,welcome_message,user_query,"How can I help you?",ClassifyIntent
CustomerBot,ClassifyIntent,,"{\"memory_key\":\"conversation_history\",\"max_memory_messages\":10}",claude,RouteQuery,HandleError,user_query|conversation_history,intent_classification,"Classify this customer query into: product_info, technical_support, billing, general. Query: {user_query}",RouteQuery
CustomerBot,RouteQuery,,Route to appropriate handler,func:route_by_intent,ProductInfo,HandleError,intent_classification,routing_decision
CustomerBot,ProductInfo,,"{\"memory_key\":\"conversation_history\"}",openai,AskFollowup,HandleError,user_query|conversation_history,response,"You are a product specialist. Help with this query: {user_query}",AskFollowup
CustomerBot,TechnicalSupport,,"{\"memory_key\":\"conversation_history\"}",openai,AskFollowup,HandleError,user_query|conversation_history,response,"You are technical support. Help with: {user_query}",AskFollowup
CustomerBot,Billing,,"{\"memory_key\":\"conversation_history\"}",openai,AskFollowup,HandleError,user_query|conversation_history,response,"You are billing support. Help with: {user_query}",AskFollowup
CustomerBot,AskFollowup,,Ask if user needs more help,input,GetQuery,End,response,followup_query,"Is there anything else I can help you with?",ClassifyIntent
CustomerBot,End,,End conversation,echo,,,response,final_message
CustomerBot,HandleError,,Handle errors,echo,GetQuery,,error,error_message
```

### Document Processing Pipeline

**Use Case:** Intelligent document analysis and summarization

```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
DocProcessor,LoadDocument,,"{\"should_split\":true,\"chunk_size\":1500,\"chunk_overlap\":200}",file_reader,AnalyzeStructure,HandleError,document_path,document_chunks
DocProcessor,AnalyzeStructure,,Analyze document structure,openai,ExtractEntities,HandleError,document_chunks,structure_analysis,"Analyze the structure and main topics of these document chunks: {document_chunks}"
DocProcessor,ExtractEntities,,Extract key entities,openai,GenerateSummary,HandleError,document_chunks,entities,"Extract key entities (people, organizations, dates, locations) from: {document_chunks}"
DocProcessor,GenerateSummary,,Generate comprehensive summary,claude,SaveResults,HandleError,document_chunks|structure_analysis|entities,comprehensive_summary,"Create a comprehensive summary incorporating structure analysis and entities: {structure_analysis} | Entities: {entities} | Content: {document_chunks}"
DocProcessor,SaveResults,,Save analysis results,json_writer,CreateReport,HandleError,comprehensive_summary|structure_analysis|entities,save_result
DocProcessor,CreateReport,,Create final report,openai,End,HandleError,comprehensive_summary|structure_analysis|entities,final_report,"Create a professional analysis report with: Summary: {comprehensive_summary} | Structure: {structure_analysis} | Key Entities: {entities}"
DocProcessor,End,,Processing complete,echo,,,final_report,completion_message
DocProcessor,HandleError,,Handle processing errors,echo,End,,error,error_message
```

### Multi-Modal Workflow with Cloud Storage

**Use Case:** Process documents from cloud storage with vector database integration

```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
CloudProcessor,LoadFromCloud,,Load document from cloud storage,cloud_json_reader,ProcessDocument,HandleError,cloud_path,document_data
CloudProcessor,ProcessDocument,,"{\"should_split\":true,\"chunk_size\":1000}",file_reader,StoreVectors,HandleError,document_data,processed_chunks
CloudProcessor,StoreVectors,,Store in vector database,vector_writer,AnalyzeContent,HandleError,processed_chunks,vector_storage_result
CloudProcessor,AnalyzeContent,,Analyze with AI,openai,SearchSimilar,HandleError,processed_chunks,analysis,"Analyze this document content: {processed_chunks}"
CloudProcessor,SearchSimilar,,Find similar documents,vector_reader,GenerateInsights,HandleError,analysis,similar_documents
CloudProcessor,GenerateInsights,,Generate insights,claude,SaveToCloud,HandleError,analysis|similar_documents,insights,"Generate insights comparing this analysis with similar documents: Analysis: {analysis} | Similar: {similar_documents}"
CloudProcessor,SaveToCloud,,Save results to cloud,cloud_json_writer,End,HandleError,insights,cloud_save_result
CloudProcessor,End,,Processing complete,echo,,,cloud_save_result,final_message
CloudProcessor,HandleError,,Handle any errors,echo,End,,error,error_message
```

### Intelligent Orchestration Workflow

**Use Case:** Dynamic routing based on user intent

```csv
GraphName,Node,Edge,Context,AgentType,Success_Next,Failure_Next,Input_Fields,Output_Field,Prompt
SmartRouter,MainOrchestrator,,"{\"matching_strategy\":\"tiered\",\"confidence_threshold\":0.8}",orchestrator,ExecuteHandler,HandleError,available_nodes|user_input,selected_handler,"Analyze user input and select the most appropriate handler"
SmartRouter,ProductSpecialist,,Product information handler,openai,GatherFeedback,HandleError,user_input,specialist_response,"I am a product specialist. User query: {user_input}. Context: I help with product features, pricing, comparisons, and availability."
SmartRouter,TechnicalSupport,,Technical support handler,openai,GatherFeedback,HandleError,user_input,specialist_response,"I am technical support. User query: {user_input}. Context: I help with troubleshooting, setup, configuration, and technical issues."
SmartRouter,BillingSupport,,Billing support handler,openai,GatherFeedback,HandleError,user_input,specialist_response,"I am billing support. User query: {user_input}. Context: I help with payments, invoices, refunds, and account billing."
SmartRouter,GeneralSupport,,General support handler,openai,GatherFeedback,HandleError,user_input,specialist_response,"I am general support. User query: {user_input}. Context: I provide general assistance and can escalate to specialists."
SmartRouter,ExecuteHandler,,Execute selected handler,func:execute_selected_handler,GatherFeedback,HandleError,selected_handler|user_input,handler_response
SmartRouter,GatherFeedback,,Collect user feedback,input,MainOrchestrator,End,specialist_response|handler_response,user_feedback,"Was this helpful? Do you have another question?"
SmartRouter,End,,Conversation complete,echo,,,specialist_response,final_response
SmartRouter,HandleError,,Handle routing errors,echo,End,,error,error_message
```

## 🛠️ CLI Reference

### Core Commands

**Run Workflows:**
```bash
# Basic execution
agentmap run --graph WorkflowName --state '{"input": "value"}'

# With custom CSV file
agentmap run --graph MyFlow --csv custom/workflow.csv --state '{"data": "test"}'

# Enable auto-compilation
agentmap run --graph MyFlow --autocompile --state '{"input": "value"}'

# Custom configuration
agentmap run --graph MyFlow --config custom_config.yaml --state '{"input": "value"}'
```

**Scaffolding:**
```bash
# Generate custom agents and functions for entire CSV
agentmap scaffold --csv workflows/my_workflow.csv

# Generate for specific graph
agentmap scaffold --graph MyWorkflow

# Custom output directories
agentmap scaffold --csv workflows/complex.csv --config custom_paths_config.yaml
```

**Graph Operations:**
```bash
# Compile graphs for performance
agentmap compile --graph ProductionWorkflow

# Export as Python code
agentmap export --graph MyFlow --output exported_workflow.py --format python

# Export with state schema
agentmap export --graph MyFlow --output workflow.py --state-schema pydantic
```

**Configuration Management:**
```bash
# View current configuration
agentmap config

# View specific config file
agentmap config --path custom_config.yaml

# Initialize storage configuration
agentmap storage-config --init

# View storage configuration
agentmap storage-config --path storage_config.yaml
```

### Scaffolding System

AgentMap's scaffolding system generates production-ready starter code:

**What Gets Generated:**

For custom agents:
```python
# Generated: agentmap/agents/custom/weather_agent.py
from agentmap.agents.base_agent import BaseAgent
from typing import Dict, Any

class WeatherAgent(BaseAgent):
    """
    Get weather data for specified location
    
    Node: WeatherNode
    Expected input fields: location
    Expected output field: weather_data
    Default prompt: Get current weather for {location}
    """
    
    def process(self, inputs: Dict[str, Any]) -> Any:
        """
        Process the inputs and return weather data.
        
        Args:
            inputs (dict): Contains input values with keys: location
            
        Returns:
            The weather data for the specified location
        """
        location = inputs.get("location")
        
        # TODO: Implement weather data retrieval
        # Example: Call weather API, process data, return results
        
        return f"Weather data for {location}: Sunny, 72°F"
```

For custom functions:
```python
# Generated: agentmap/functions/custom_router.py
from typing import Dict, Any

def custom_router(state: Any, success_node="Success", failure_node="Failure") -> str:
    """
    Custom routing logic based on state analysis.
    
    Args:
        state: The current graph state
        success_node (str): Node to route to on success
        failure_node (str): Node to route to on failure
        
    Returns:
        str: Name of the next node to execute
    
    Available in state:
    - user_input: Input from user
    - processed_data: Data from processing step
    """
    
    # TODO: Implement custom routing logic
    # Example: Analyze state contents and determine routing
    
    if state.get("last_action_success", True):
        return success_node
    else:
        return failure_node
```

### Development Workflow

**Typical Development Cycle:**

1. **Design:** Create CSV workflow definition
2. **Scaffold:** Generate custom components
   ```bash
   agentmap scaffold --csv my_workflow.csv
   ```
3. **Implement:** Fill in generated code templates
4. **Test:** Run workflow with test data
   ```bash
   agentmap run --graph TestFlow --state '{"test": "data"}'
   ```
5. **Debug:** Use execution tracking to identify issues
6. **Deploy:** Compile for production
   ```bash
   agentmap compile --graph ProductionFlow
   ```

## 🏗️ Architecture Overview

### System Components

```
AgentMap Architecture
├── 🎯 CSV Definition Layer
│   ├── Workflow definitions
│   ├── Node specifications  
│   └── Routing logic
│
├── 🤖 Agent Layer
│   ├── Built-in agents (20+ types)
│   ├── Custom agent scaffolding
│   └── LLM integrations
│
├── 🧠 Orchestration Layer
│   ├── Graph assembly
│   ├── Dynamic routing
│   ├── State management
│   └── Execution tracking
│
├── 💾 Storage Layer
│   ├── Local file systems
│   ├── Cloud storage providers
│   ├── Vector databases
│   └── Document processing
│
└── 🛠️ Developer Tools
    ├── CLI interface
    ├── Code generation
    ├── Configuration management
    └── Monitoring & debugging
```

### Data Flow Architecture

```
User Input → CSV Parser → Graph Builder → Agent Registry → Execution Engine
     ↓            ↓            ↓             ↓              ↓
State Init → Node Creation → Agent Loading → State Flow → Result Output
```

### Key Design Patterns

**1. Declarative Configuration**
- Workflows defined in CSV format
- Separation of logic from configuration
- Version control friendly

**2. Agent-Based Architecture**
- Modular, pluggable components
- Consistent interface across all agents
- Easy extensibility

**3. State-Driven Execution**
- Immutable state transitions
- Clear data flow between nodes
- Comprehensive execution tracking

**4. Service-Oriented Design**
- Storage abstraction layers
- Dependency injection
- Testable components

## 📚 Best Practices

### Workflow Design

**1. Start Simple, Scale Gradually**
```csv
# Good: Simple, clear workflow
SimpleFlow,Input,echo,Process,,user_input,processed_input
SimpleFlow,Process,default,Output,,processed_input,result,"Process: {processed_input}"
SimpleFlow,Output,echo,,,result,final_output
```

**2. Use Descriptive Node Names**
```csv
# Good: Clear purpose
UserRegistration,ValidateEmail,branching,CreateAccount,HandleValidationError,email,validation_result
UserRegistration,CreateAccount,default,SendWelcome,,email|validation_result,account_data

# Avoid: Generic names
UserRegistration,Node1,branching,Node2,Node3,email,result
```

**3. Implement Comprehensive Error Handling**
```csv
# Always include error handling paths
DataFlow,ProcessData,default,SaveResults,HandleProcessingError,input,processed_data
DataFlow,SaveResults,csv_writer,Success,HandleSaveError,processed_data,save_result
DataFlow,HandleProcessingError,echo,End,,error,error_message
DataFlow,HandleSaveError,echo,End,,error,error_message
```

### Memory Management

**1. Set Appropriate Memory Limits**
```csv
# Good: Reasonable memory limits
ChatBot,Respond,"{\"memory_key\":\"chat_history\",\"max_memory_messages\":20}",openai,user_input|chat_history,response,"You are helpful: {user_input}"

# Avoid: Unlimited memory in production
ChatBot,Respond,"{\"memory_key\":\"chat_history\"}",openai,user_input|chat_history,response,"You are helpful: {user_input}"
```

**2. Use Meaningful Memory Keys**
```csv
# Good: Descriptive memory keys
CustomerService,Respond,"{\"memory_key\":\"customer_conversation\"}",claude,user_query|customer_conversation,response
TechnicalSupport,Respond,"{\"memory_key\":\"technical_session\"}",openai,user_issue|technical_session,response

# Avoid: Generic memory keys
CustomerService,Respond,"{\"memory_key\":\"memory\"}",claude,user_query|memory,response
```

### Performance Optimization

**1. Use Appropriate Agent Types**
```csv
# Good: Efficient for simple operations
DataFlow,PassThrough,echo,NextStep,,data,data
DataFlow,SimpleMessage,default,NextStep,,data,message,"Processing {data}"

# Avoid: Overusing LLM agents for simple tasks
DataFlow,PassThrough,openai,NextStep,,data,data,"Just return: {data}"
```

**2. Implement Intelligent Caching**
```yaml
# In configuration
prompts:
  enable_cache: true
  
execution:
  tracking:
    enabled: true  # Only when needed
```

**3. Design for Parallel Execution**
```csv
# Use multiple success targets for parallel processing
Parallel,Distribute,default,ProcessorA|ProcessorB|ProcessorC,,data,distributed_tasks
Parallel,ProcessorA,default,Combine,,distributed_tasks.a,result_a
Parallel,ProcessorB,default,Combine,,distributed_tasks.b,result_b
Parallel,ProcessorC,default,Combine,,distributed_tasks.c,result_c
Parallel,Combine,default,End,,result_a|result_b|result_c,combined_results
```

### Security & Configuration

**1. Use Environment Variables for Secrets**
```yaml
# Good: Environment variable references
llm:
  openai:
    api_key: "env:OPENAI_API_KEY"
  anthropic:
    api_key: "env:ANTHROPIC_API_KEY"

# Avoid: Hardcoded keys
llm:
  openai:
    api_key: "sk-1234567890abcdef"
```

**2. Implement Input Validation**
```csv
# Include validation steps
UserFlow,ValidateInput,branching,ProcessInput,HandleInvalidInput,user_input,validation_result
UserFlow,ProcessInput,default,SaveResult,HandleProcessingError,user_input,processed_result
```

### Testing & Debugging

**1. Enable Detailed Tracking During Development**
```yaml
execution:
  tracking:
    enabled: true
    track_inputs: true
    track_outputs: true
  success_policy:
    type: "all_nodes"
```

**2. Create Test Workflows**
```csv
# Create simplified test versions
TestFlow,MockInput,default,TestProcessor,,test_data,mock_input,"Test input: {test_data}"
TestFlow,TestProcessor,echo,ValidateOutput,,mock_input,processed_output
TestFlow,ValidateOutput,branching,Success,Failure,processed_output,validation_result
```

**3. Use Execution Path Analysis**
```python
# Monitor execution paths
result = run_graph("ComplexFlow", test_state)

print("Execution Summary:")
print(f"Success: {result['graph_success']}")
print(f"Duration: {result.get('total_duration', 0):.2f}s")

for step in result.get("execution_steps", []):
    status = "✅" if step["success"] else "❌"
    print(f"  {status} {step['node']} ({step['duration']:.3f}s)")
```

## 🔍 Troubleshooting

### Common Issues and Solutions

**1. CSV Format Errors**
```
Error: InvalidEdgeDefinitionError
Solution: Don't use both Edge and Success_Next/Failure_Next in the same row
```

**2. Agent Not Found**
```
Error: Agent type 'custom_agent' not found
Solution: 
- Run: agentmap scaffold --csv your_workflow.csv
- Implement the generated agent class
- Ensure agent is in the correct directory
```

**3. Memory Issues**
```
Error: Memory serialization failed
Solution:
- Check memory_key is included in Input_Fields
- Verify memory configuration syntax
- Ensure consistent memory_key across nodes
```

**4. LLM Configuration**
```
Error: OpenAI API key not found
Solution:
- Set environment variable: export OPENAI_API_KEY="your-key"
- Or configure in agentmap_config.yaml
- Verify key is valid and has sufficient credits
```

**5. Storage Configuration**
```
Error: Collection 'users.json' not found
Solution:
- Check file path in storage_config.yaml
- Verify file exists and has correct permissions
- For cloud storage, check credentials and container/bucket access
```

### Debug Workflow

**1. Enable Verbose Logging**
```python
from agentmap.logging import get_logger

logger = get_logger("MyApp")
logger.setLevel("DEBUG")  # Enable detailed logging

result = run_graph("MyWorkflow", initial_state)
```

**2. Inspect State at Each Step**
```python
# Add debug nodes to inspect state
def debug_state(inputs):
    print(f"Current state: {inputs}")
    return inputs

# Or use echo agents strategically
```

**3. Test Individual Nodes**
```python
# Test specific agents in isolation
from agentmap.agents.registry import get_agent

agent = get_agent("openai")
result = agent.run({"test_input": "Hello"}, {"prompt": "Say hello back"})
```

## 📖 Additional Resources

### Documentation
- [AgentMap Documentation Site](https://jwwelbor.github.io/AgentMap)
- [API Reference](https://github.com/jwwelbor/AgentMap/wiki)
- [Example Workflows](https://github.com/jwwelbor/AgentMap/tree/main/examples)

### Community
- [GitHub Issues](https://github.com/jwwelbor/AgentMap/issues)
- [Discussions](https://github.com/jwwelbor/AgentMap/discussions)
- [Contributing Guide](https://github.com/jwwelbor/AgentMap/blob/main/CONTRIBUTING.md)

### Related Projects
- [LangGraph](https://github.com/langchain-ai/langgraph) - The underlying workflow engine
- [LangChain](https://github.com/langchain-ai/langchain) - AI application framework
- [FastAPI](https://fastapi.tiangolo.com/) - API framework used in AgentMap server

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
2. **Create a feature branch:** `git checkout -b feature/amazing-feature`
3. **Make your changes and add tests**
4. **Run tests:** `pytest tests/`
5. **Commit changes:** `git commit -m 'Add amazing feature'`
6. **Push to branch:** `git push origin feature/amazing-feature`
7. **Open a Pull Request**

### Development Setup
```bash
# Clone and setup development environment
git clone https://github.com/jwwelbor/AgentMap.git
cd AgentMap

# Install development dependencies
pip install -e ".[dev,all]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=agentmap tests/
```

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **LangGraph Team** - For the powerful workflow engine
- **LangChain Community** - For the comprehensive AI toolkit
- **Open Source Contributors** - For making this project possible

---

**Ready to build your next AI workflow? Start with AgentMap today!**

```bash
pip install agentmap
agentmap scaffold --csv your_workflow.csv
```
