# TypeDialog Agents - Installation Guide

Complete installation guide for TypeDialog Agents system.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Install](#quick-install)
3. [Detailed Installation](#detailed-installation)
4. [Configuration](#configuration)
5. [Verification](#verification)
6. [Troubleshooting](#troubleshooting)

---

## Prerequisites

### System Requirements

**Minimum:**

- CPU: 2 cores
- RAM: 4 GB
- Disk: 1 GB free space
- OS: Linux, macOS, or Windows (WSL2)

**Recommended:**

- CPU: 4+ cores
- RAM: 8 GB
- Disk: 5 GB free space (for cache and builds)
- OS: Linux (Ubuntu 22.04+) or macOS (12.0+)

### Software Requirements

1. **Rust** (1.75.0 or later)

   ```bash
   # Install Rust via rustup
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

   # Verify installation
   rustc --version
   cargo --version
   ```

2. **Git**

   ```bash
   # Ubuntu/Debian
   sudo apt-get install git

   # macOS
   brew install git

   # Verify
   git --version
   ```

3. **Build Tools**

   **Ubuntu/Debian:**

   ```bash
   sudo apt-get update
   sudo apt-get install build-essential pkg-config libssl-dev
   ```

   **macOS:**

   ```bash
   xcode-select --install
   ```

   **Fedora/RHEL:**

   ```bash
   sudo dnf groupinstall "Development Tools"
   sudo dnf install openssl-devel
   ```

4. **Optional: Docker** (for containerized deployment)

   ```bash
   # Ubuntu/Debian
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh

   # Verify
   docker --version
   docker-compose --version
   ```

---

## Quick Install

For experienced users who want to get started immediately:

```bash
# 1. Clone repository
git clone https://github.com/yourusername/typedialog.git
cd typedialog

# 2. Build release binary
cargo build --release --package typedialog-ag

# 3. Install binary (optional)
sudo cp target/release/typedialog-ag /usr/local/bin/

# 4. Set API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# 5. Test installation
typedialog-ag validate agents/greeting.agent.mdx
```text

Done! Skip to [Configuration](#configuration).

---

## Detailed Installation

### Step 1: Clone Repository

```bash
# Clone from GitHub
git clone https://github.com/yourusername/typedialog.git
cd typedialog

# Or clone via SSH
git clone git@github.com:yourusername/typedialog.git
cd typedialog

# Verify
ls -la
# Should see: Cargo.toml, agents/, crates/, etc.
```text

### Step 2: Build from Source

#### Development Build (Debug)

Faster compilation, slower runtime:

```bash
cargo build --package typedialog-ag

# Binary location
./target/debug/typedialog-ag --version
```text

#### Production Build (Release)

Optimized for performance:

```bash
cargo build --release --package typedialog-ag

# Binary location
./target/release/typedialog-ag --version
```text

Build time: ~3-5 minutes (first time, with clean cache)

#### Build All Packages

```bash
# Build core library + CLI + server
cargo build --release --workspace

# Verify all binaries
ls -lh target/release/typedialog-ag*
```text

### Step 3: Install Binary

#### System-Wide Installation (Recommended)

**Linux/macOS:**

```bash
# Copy to /usr/local/bin
sudo cp target/release/typedialog-ag /usr/local/bin/

# Verify
which typedialog-ag
typedialog-ag --version
```text

**macOS (Homebrew style):**

```bash
# Copy to Homebrew cellar
sudo cp target/release/typedialog-ag /opt/homebrew/bin/

# Verify
which typedialog-ag
```text

#### User-Only Installation

```bash
# Create local bin directory
mkdir -p ~/.local/bin

# Copy binary
cp target/release/typedialog-ag ~/.local/bin/

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or ~/.zshrc

# Verify
typedialog-ag --version
```text

#### Development Mode (No Install)

Use directly from build directory:

```bash
# Create alias (add to ~/.bashrc or ~/.zshrc)
alias typedialog-ag='~/path/to/typedialog/target/release/typedialog-ag'

# Or use full path
~/typedialog/target/release/typedialog-ag --version
```text

### Step 4: Install Example Agents

```bash
# Option 1: Use from repository
cd /path/to/typedialog
typedialog-ag validate agents/greeting.agent.mdx

# Option 2: Copy to standard location
mkdir -p ~/.typeagent/agents
cp -r agents/* ~/.typeagent/agents/

# Option 3: System-wide agents (requires sudo)
sudo mkdir -p /etc/typeagent/agents
sudo cp -r agents/* /etc/typeagent/agents/
```text

---

## Configuration

### Environment Variables

Create `.env` file or export variables:

```bash
# Required: Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional: OpenAI (if using GPT models via Codex)
export OPENAI_API_KEY=sk-your-openai-key

# Optional: Custom cache directory
export TYPEAGENT_CACHE_DIR=$HOME/.typeagent/cache

# Optional: Logging level
export RUST_LOG=info  # Options: error, warn, info, debug, trace
```text

**Persistent Configuration:**

Add to `~/.bashrc` or `~/.zshrc`:

```bash
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc
```text

### Configuration File

Create `~/.typeagent/config.yaml`:

```yaml
# Default configuration for TypeAgent CLI

# Cache settings
cache:
  strategy: Both  # Options: Memory, Disk, Both, None
  max_entries: 1000
  cache_dir: ~/.typeagent/cache

# Agent paths
agent_paths:
  - ~/.typeagent/agents
  - /etc/typeagent/agents
  - ./agents

# HTTP Server defaults
server:
  host: 127.0.0.1
  port: 8765
  cors: true

# LLM defaults
llm:
  default_model: claude-3-5-sonnet-20241022
  default_temperature: 0.7
  default_max_tokens: 4096
```text

### Permissions

Set correct permissions:

```bash
# Configuration directory
chmod 700 ~/.typeagent
chmod 600 ~/.typeagent/config.yaml

# Binary (if installed)
sudo chmod 755 /usr/local/bin/typedialog-ag

# Agents directory
chmod 755 ~/.typeagent/agents
chmod 644 ~/.typeagent/agents/*.agent.mdx
```text

---

## Verification

### Test Installation

```bash
# 1. Check version
typedialog-ag --version

# 2. Validate example agent
typedialog-ag validate agents/greeting.agent.mdx

# 3. Transpile agent
typedialog-ag transpile agents/greeting.agent.mdx

# 4. Check cache
typedialog-ag cache stats

# 5. Run test suite (from repo)
./test-agents.sh
```text

Expected output:

```text
✓ MDX syntax valid
✓ Transpilation successful
✓ Type checking passed
✓ Evaluation successful

Agent Summary:
  Role: friendly assistant
  Model: claude-3-5-haiku-20241022
  Max tokens: 4096
  Temperature: 0.7
```text

### Test HTTP Server

Terminal 1 - Start server:

```bash
typedialog-ag serve --port 8765
```text

Terminal 2 - Test endpoints:

```bash
# Health check
curl http://localhost:8765/health
# Expected: OK

# Validate agent
curl -X POST http://localhost:8765/validate \
  -H "Content-Type: application/json" \
  -d '{"agent_file":"agents/greeting.agent.mdx"}'
# Expected: {"valid":true, ...}
```text

### Test with API Key

```bash
# Set API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Execute agent (requires API key)
echo '{"name":"Test"}' | typedialog-ag agents/greeting.agent.mdx --inputs -
```text

If successful, you'll see a response from Claude.

---

## Troubleshooting

### Build Errors

**Error: `linker 'cc' not found`**

```bash
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install
```text

**Error: `could not find openssl`**

```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev pkg-config

# macOS
brew install openssl
export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl/lib/pkgconfig"
```text

**Error: Out of memory during build**

```bash
# Reduce parallel jobs
cargo build --release -j 2
```text

### Runtime Errors

**Error: `command not found: typedialog-ag`**

```bash
# Check installation
which typedialog-ag

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or reinstall
sudo cp target/release/typedialog-ag /usr/local/bin/
```text

**Error: `ANTHROPIC_API_KEY not set`**

```bash
# Set environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Or add to ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc
```text

**Error: `Permission denied`**

```bash
# Fix permissions
chmod +x /usr/local/bin/typedialog-ag

# Or run with full path
~/typedialog/target/release/typedialog-ag
```text

**Error: `Address already in use (port 8765)`**

```bash
# Find process using port
lsof -i :8765

# Kill process
kill -9 <PID>

# Or use different port
typedialog-ag serve --port 9000
```text

### Cache Issues

**Cache not working:**

```bash
# Clear cache
typedialog-ag cache clear

# Check cache stats
typedialog-ag cache stats

# Verify cache directory exists
ls -la ~/.typeagent/cache/
```text

**Cache directory permissions:**

```bash
# Fix permissions
chmod 700 ~/.typeagent
chmod 700 ~/.typeagent/cache
```text

### Agent Validation Errors

**Error: `Failed to parse MDX`**

- Check YAML frontmatter syntax
- Ensure `---` delimiters are correct
- Validate directive syntax (`@agent`, `@input`, etc.)

**Error: `Failed to transpile`**

- Verify agent directive has valid fields
- Check for typos in field names
- Ensure proper quoting in YAML

**Error: `Type checking failed`**

- Usually indicates Nickel evaluation issue
- Run with verbose logging: `RUST_LOG=debug typedialog-ag validate ...`

---

## Updating

### Update from Git

```bash
cd /path/to/typedialog

# Pull latest changes
git pull origin main

# Rebuild
cargo build --release --package typedialog-ag

# Reinstall
sudo cp target/release/typedialog-ag /usr/local/bin/
```text

### Update Dependencies

```bash
# Update Cargo.lock
cargo update

# Rebuild
cargo build --release --package typedialog-ag
```text

### Clean Rebuild

```bash
# Clean all build artifacts
cargo clean

# Rebuild from scratch
cargo build --release --package typedialog-ag
```text

---

## Uninstallation

### Remove Binary

```bash
# System-wide installation
sudo rm /usr/local/bin/typedialog-ag

# User installation
rm ~/.local/bin/typedialog-ag
```text

### Remove Configuration

```bash
# Remove config and cache
rm -rf ~/.typeagent

# Remove repository
rm -rf ~/path/to/typedialog
```text

### Remove Environment Variables

Edit `~/.bashrc` or `~/.zshrc` and remove:

```bash
export ANTHROPIC_API_KEY=...
export PATH="$HOME/.local/bin:$PATH"  # If added for typeagent
```text

Then reload:

```bash
source ~/.bashrc  # or ~/.zshrc
```text

---

## Next Steps

After successful installation:

1. Read [quickstart.md](../quickstart.md) for usage examples
2. Read [deployment.md](../deployment.md) for production deployment
3. Explore example agents in `agents/` directory
4. Create your first custom agent
5. Start HTTP server for API access

## Support

- **Issues**: Report bugs at GitHub repository
- **Documentation**: See `docs/` directory
- **Examples**: See `agents/` directory
- **Tests**: Run `./test-agents.sh`
