jesus/TypeDialog

Fork 0

Jesús Pérez f490760395

chore: fragments multiple paths and fix md errors

2025-12-26 23:24:53 +00:00

9.3 KiB

Raw Blame History

TypeDialog Agents - Quick Start Guide

Installation

cd /Users/Akasha/Development/typedialog
cargo build --release --package typedialog-ag

The binary will be at: ./target/release/typedialog-ag

Setup

Configure your API key:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Example Agents

The agents/ directory contains 9 production-ready example agents:

Agent	Purpose	Model	Best For
greeting	Friendly greetings	Haiku	Simple interactions
code-reviewer	Code review	Opus 4.5	Quality assurance
architect	Architecture design	Opus 4.5	System design
summarizer	Text summarization	Sonnet	Content processing
test-generator	Generate tests	Sonnet	Test automation
doc-generator	Documentation	Sonnet	API docs
translator	Language translation	Sonnet	i18n
debugger	Debug issues	Opus 4.5	Troubleshooting
refactor	Code refactoring	Opus 4.5	Code quality

Usage

1. CLI Mode (Interactive)

# Execute agent with interactive prompts
./target/release/typedialog-ag agents/greeting.agent.mdx
# Will prompt: name (String)
# Enter: Alice
# Response: Warm greeting for Alice

# Execute with predefined inputs
echo '{"name":"Bob"}' | ./target/release/typedialog-ag agents/greeting.agent.mdx --inputs -

2. Validate Agents

# Validate syntax and configuration
./target/release/typedialog-ag validate agents/code-reviewer.agent.mdx

# Output:
# ✓ MDX syntax valid
# ✓ Transpilation successful
# ✓ Type checking passed
# ✓ Evaluation successful
#
# Agent Summary:
#   Role: senior code reviewer
#   Model: claude-opus-4-5-20251101
#   Max tokens: 4096
#   Temperature: 0.7

3. Transpile to Nickel

# See the generated Nickel configuration
./target/release/typedialog-ag transpile agents/architect.agent.mdx

# Output: Nickel code with full configuration

4. HTTP Server Mode

Start the server:

./target/release/typedialog-ag serve --port 8765

Output:

🚀 Starting TypeAgent HTTP Server

⚙️  Configuration:
   Config: defaults
   Host: 127.0.0.1
   Port: 8765
   Address: http://127.0.0.1:8765

🤖 Available Agents (9):
   • architect
   • code-reviewer
   • debugger
   • doc-generator
   • greeting
   • refactor
   • summarizer
   • test-generator
   • translator

📡 API Endpoints:
   GET  /health                    - Health check
   POST /execute                   - Execute agent from file
   POST /agents/{name}/execute     - Execute agent by name
   POST /transpile                 - Transpile MDX to Nickel
   POST /validate                  - Validate agent file

Press Ctrl+C to stop the server

5. HTTP API Examples

Execute greeting agent

curl -X POST http://localhost:8765/agents/greeting/execute \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice"
  }'

Response:

{
  "output": "Hello Alice! I hope you're having a wonderful day...",
  "validation_passed": true,
  "validation_errors": [],
  "metadata": {
    "duration_ms": 1234,
    "tokens": 45,
    "model": "claude-3-5-haiku-20241022"
  }
}

Code Review

curl -X POST http://localhost:8765/agents/code-reviewer/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "rust",
    "code": "fn add(a: i32, b: i32) -> i32 { a + b }"
  }'

Response includes structured review with sections:

Review
Suggestions
Security Considerations

Architecture Design

curl -X POST http://localhost:8765/agents/architect/execute \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "Real-time collaborative document editor",
    "tech_stack": "Rust, WebSockets, PostgreSQL, Redis"
  }'

Response includes:

Architecture
Components
Data Flow
Technical Considerations
Implementation Strategy

Generate Tests

curl -X POST http://localhost:8765/agents/test-generator/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "function_code": "def factorial(n):\n    return 1 if n == 0 else n * factorial(n-1)"
  }'

Debug Code

curl -X POST http://localhost:8765/agents/debugger/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "rust",
    "code": "let v = vec![1,2,3]; println!(\"{}\", v[5]);",
    "error": "index out of bounds: the len is 3 but the index is 5"
  }'

Response includes:

Root Cause
Fix
Prevention
Testing

Refactor Code

curl -X POST http://localhost:8765/agents/refactor/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "typescript",
    "code": "function calc(a,b,op){if(op=='+')return a+b;if(op=='-')return a-b;}",
    "goal": "Improve type safety and readability"
  }'

Cache Management

TypeDialog automatically caches transpiled Nickel code for faster execution:

# View cache statistics
./target/release/typedialog-ag cache stats

# Output:
# 📊 Cache Statistics
#
# Strategy:
#   Both { max_entries: 1000, cache_dir: "/Users/.../.typeagent/cache" }
#
# Entries:
#   Memory: 5
#   Disk: 9
#   Total: 14
#
# Location:
#   /Users/.../.typeagent/cache
#   Size: 12.34 KB

# Clear cache
./target/release/typedialog-ag cache clear

Advanced Features

Optional Inputs

Agents support optional inputs with ? suffix:

@input feature: String
@input tech_stack?: String  # Optional

Usage:

# With optional input
curl -X POST http://localhost:8765/agents/architect/execute \
  -d '{"feature":"Chat","tech_stack":"Rust"}'

# Without optional input (uses default)
curl -X POST http://localhost:8765/agents/architect/execute \
  -d '{"feature":"Chat"}'

Conditional Template Logic

Agents use Tera templates (Jinja2-like):

{% if tech_stack %}
**Tech Stack**: {{ tech_stack }}
{% else %}
**Tech Stack**: Choose appropriate technologies
{% endif %}

Output Validation

Agents enforce quality with validation rules:

@validate output {
  must_contain: ["## Review", "## Suggestions"],
  format: markdown,
  min_length: 100,
  max_length: 5000
}

Performance

First Run (Cold Start)

Parse MDX:       ~5ms
Transpile:      ~10ms
Evaluate:       ~15ms
LLM Execution:  ~2000ms (varies by model)
Total:          ~2030ms

Subsequent Runs (Cached)

Cache Hit:       ~0ms (instant)
Evaluate:       ~15ms
LLM Execution:  ~2000ms
Total:          ~2015ms (15ms faster)

Speedup

~2x faster for agent loading
Cache persists across restarts
Automatic invalidation on file changes (mtime-based)

Testing

Run the comprehensive test suite:

./test-agents.sh