enya-agent 0.1.0

package/docs/content/channels/whatsapp.md

@@ -0,0 +1,240 @@
++++
+title = "WhatsApp"
+weight = 3
++++
+
+# WhatsApp Channel
+
+Deploy your Enact agent to WhatsApp via Meta Business API.
+
+## Status
+
+| Feature | Status |
+|---------|--------|
+| Cloud API Integration | ✅ Implemented |
+| Text Messages | ✅ Implemented |
+| Interactive Messages | ✅ Implemented |
+| Message Templates | ✅ Implemented |
+| Media Messages | ✅ Implemented |
+| Webhook Handling | ✅ Implemented |
+
+## Setup
+
+### 1. Create Meta Business Account
+
+1. Go to [Meta Business Suite](https://business.facebook.com)
+2. Create or select a business account
+3. Go to [Meta for Developers](https://developers.facebook.com)
+4. Create a new app (type: Business)
+
+### 2. Set Up WhatsApp
+
+1. In your app dashboard, add the WhatsApp product
+2. Complete business verification
+3. Set up a test phone number or add your business number
+
+### 3. Get Credentials
+
+From WhatsApp > API Setup:
+- **Phone Number ID**
+- **Access Token**
+- **Webhook Verify Token** (create your own)
+
+### 4. Configure Environment
+
+```bash
+# .env
+WHATSAPP_PHONE_NUMBER_ID=123456789012345
+WHATSAPP_ACCESS_TOKEN=EAABc...
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-secret-token
+WHATSAPP_APP_SECRET=your-app-secret  # For signature verification
+```
+
+### 5. Run Channel (Rust API)
+
+```rust
+use enact_channels::whatsapp::{WhatsAppChannel, WhatsAppConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let config = WhatsAppConfig {
+        phone_number_id: std::env::var("WHATSAPP_PHONE_NUMBER_ID")?,
+        access_token: std::env::var("WHATSAPP_ACCESS_TOKEN")?,
+        webhook_verify_token: std::env::var("WHATSAPP_WEBHOOK_VERIFY_TOKEN")?,
+        app_secret: std::env::var("WHATSAPP_APP_SECRET").ok(),
+        ..Default::default()
+    };
+
+    let channel = WhatsAppChannel::new(config)?;
+    channel.run().await?;
+
+    Ok(())
+}
+```
+
+## Configuration Options
+
+```rust
+pub struct WhatsAppConfig {
+    /// WhatsApp Business Phone Number ID
+    pub phone_number_id: String,
+
+    /// Meta Graph API Access Token
+    pub access_token: String,
+
+    /// Webhook verification token
+    pub webhook_verify_token: String,
+
+    /// App secret for signature verification
+    pub app_secret: Option<String>,
+
+    /// Graph API version
+    pub api_version: String,  // default: "v18.0"
+}
+```
+
+## Features
+
+### Text Messages
+
+```rust
+channel.send(OutgoingMessage {
+    to: recipient_phone.clone(),
+    message_type: MessageContent::Text {
+        body: "Hello from Enact!".to_string(),
+        preview_url: false,
+    },
+}).await?;
+```
+
+### Interactive Messages
+
+```rust
+use enact_channels::whatsapp::{Interactive, Button};
+
+// Button message (max 3 buttons)
+let buttons = Interactive::Buttons {
+    body: "How can I help?".to_string(),
+    buttons: vec![
+        Button::new("btn_order", "Check Order"),
+        Button::new("btn_support", "Get Support"),
+        Button::new("btn_info", "More Info"),
+    ],
+};
+
+channel.send(OutgoingMessage {
+    to: recipient_phone,
+    message_type: MessageContent::Interactive(buttons),
+}).await?;
+```
+
+### List Messages
+
+```rust
+let list = Interactive::List {
+    body: "Select a category:".to_string(),
+    button: "View Options".to_string(),
+    sections: vec![
+        ListSection {
+            title: "Products".to_string(),
+            rows: vec![
+                ListRow::new("prod_1", "Product A", Some("Description")),
+                ListRow::new("prod_2", "Product B", Some("Description")),
+            ],
+        },
+    ],
+};
+```
+
+### Message Templates
+
+For initiating conversations:
+
+```rust
+channel.send_template(SendTemplate {
+    to: customer_phone,
+    template_name: "order_confirmation".to_string(),
+    language_code: "en".to_string(),
+    components: vec![
+        TemplateComponent::Body {
+            parameters: vec![
+                Parameter::Text("John".to_string()),
+                Parameter::Text("ORD-12345".to_string()),
+            ],
+        },
+    ],
+}).await?;
+```
+
+### Media Messages
+
+```rust
+// Send image
+channel.send(OutgoingMessage {
+    to: recipient_phone,
+    message_type: MessageContent::Image {
+        link: "https://example.com/image.png".to_string(),
+        caption: Some("Check this out!".to_string()),
+    },
+}).await?;
+
+// Send document
+channel.send(OutgoingMessage {
+    to: recipient_phone,
+    message_type: MessageContent::Document {
+        link: "https://example.com/report.pdf".to_string(),
+        filename: "report.pdf".to_string(),
+        caption: Some("Your report".to_string()),
+    },
+}).await?;
+```
+
+## Webhook Setup
+
+WhatsApp requires a webhook endpoint:
+
+```rust
+use axum::{Router, routing::{get, post}};
+
+let app = Router::new()
+    .route("/webhook", get(webhook_verify))
+    .route("/webhook", post(webhook_handler));
+
+async fn webhook_verify(Query(params): Query<VerifyParams>) -> impl IntoResponse {
+    if params.hub_verify_token == config.webhook_verify_token {
+        params.hub_challenge
+    } else {
+        "Invalid token".to_string()
+    }
+}
+```
+
+**Configure in Meta:**
+1. Go to WhatsApp > Configuration
+2. Add webhook URL: `https://your-domain.com/webhook`
+3. Enter your verify token
+4. Subscribe to: `messages`
+
+## Rate Limits
+
+| Tier | Messages/day | Requirement |
+|------|--------------|-------------|
+| Unverified | 250 | Testing only |
+| Tier 1 | 1,000 | Business verified |
+| Tier 2 | 10,000 | High quality rating |
+| Tier 3 | 100,000 | High quality rating |
+| Tier 4 | Unlimited | High quality rating |
+
+## Security
+
+### Signature Verification
+
+Verify webhook requests:
+
+```rust
+fn verify_signature(payload: &[u8], signature: &str, app_secret: &str) -> bool {
+    let expected = hmac_sha256(app_secret.as_bytes(), payload);
+    let expected_hex = format!("sha256={}", hex::encode(expected));
+    signature == expected_hex
+}
+```

package/docs/content/cli/_index.md

@@ -0,0 +1,261 @@
++++
+title = "CLI Reference"
+weight = 3
+sort_by = "weight"
++++
+
+# CLI Reference
+
+The `enact` command-line interface for running agents and managing the gateway.
+
+## Status
+
+| Command | Status |
+|---------|--------|
+| `enact --help` | ✅ Complete |
+| `enact version` | ✅ Complete |
+| `enact doctor` | ✅ Complete |
+| `enact run` | ✅ Complete |
+| `enact serve` | ✅ Complete |
+
+## Installation
+
+```bash
+# Build from source
+git clone https://github.com/adl-tan-theta/enactai.git
+cd enya/enact-agent
+cargo build --release
+
+# Binary is at ./target/release/enact
+
+# OR install via Cargo (recommended)
+cargo install enact
+
+# OR via npm
+npm install -g enact
+```
+
+## Commands
+
+### `enact --help`
+
+Show all available commands.
+
+```bash
+./target/release/enact --help
+```
+
+### `enact version`
+
+Display version information.
+
+```bash
+./target/release/enact version
+# enact 0.0.1
+```
+
+### `enact doctor`
+
+Run system diagnostics and check configuration.
+
+```bash
+./target/release/enact doctor
+```
+
+**Output:**
+```
+Enact System Check
+
+┌───────────┬────────┬─────────────────────────────────────────┐
+│ Component │ Status │ Details                                 │
+├───────────┼────────┼─────────────────────────────────────────┤
+│ API Key   │ ✓      │ Configured                              │
+│ WhatsApp  │ ○      │ Optional - not configured               │
+│ Model     │ ✓      │ gpt-4o-mini (default)                   │
+└───────────┴────────┴─────────────────────────────────────────┘
+
+Environment Variables:
+  ✓ set OPENAI_API_KEY
+    not set AZURE_OPENAI_API_KEY
+    not set OPENAI_BASE_URL
+  ✓ set OPENAI_MODEL
+    not set WHATSAPP_ACCESS_TOKEN
+    not set WHATSAPP_ENDPOINT_ID
+    not set WHATSAPP_VERIFY_TOKEN
+    not set WHATSAPP_APP_SECRET
+```
+
+### `enact run`
+
+Execute an agent with the given input.
+
+```bash
+./target/release/enact run --input "What is the capital of France?"
+```
+
+**Options:**
+- `--input <TEXT>` - The input to send to the agent (required)
+- `--agent <NAME>` - Agent name (default: "default")
+- `--system-prompt <TEXT>` - Override system prompt
+
+**Environment Variables:**
+- `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` - API key (required)
+- `OPENAI_BASE_URL` - API base URL (default: `https://api.openai.com`)
+- `OPENAI_MODEL` - Model to use (default: `gpt-4o-mini`)
+
+**Example:**
+```bash
+OPENAI_API_KEY="sk-..." ./target/release/enact run \
+  --input "Explain quantum computing in simple terms"
+```
+
+### `enact serve`
+
+Start the HTTP gateway server.
+
+```bash
+./target/release/enact serve --http-port 8080
+```
+
+**Options:**
+- `--http-port <PORT>` - Port to listen on (default: 8080)
+- `--air-gapped` - Run in air-gapped mode (disable external network calls)
+
+**Environment Variables:**
+- `WHATSAPP_ACCESS_TOKEN` - WhatsApp API token (required for WhatsApp)
+- `WHATSAPP_ENDPOINT_ID` - WhatsApp phone number ID (required for WhatsApp)
+- `WHATSAPP_VERIFY_TOKEN` - Webhook verification token (required for WhatsApp)
+- `WHATSAPP_APP_SECRET` - App secret for signature verification (optional)
+- `WHATSAPP_ALLOWED_NUMBERS` - Comma-separated list of allowed phone numbers (default: `*`)
+- `OPENAI_API_KEY` - API key for agent responses (optional, falls back to echo mode)
+
+**Example:**
+```bash
+WHATSAPP_ACCESS_TOKEN="EAABc..." \
+WHATSAPP_ENDPOINT_ID="123456789012345" \
+WHATSAPP_VERIFY_TOKEN="my-secret-token" \
+OPENAI_API_KEY="sk-..." \
+./target/release/enact serve --http-port 8080
+```
+
+## Gateway Endpoints
+
+When running `enact serve`, the following endpoints are available:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/webhook/whatsapp` | GET | WhatsApp webhook verification |
+| `/webhook/whatsapp` | POST | WhatsApp message webhook |
+
+### Health Check
+
+```bash
+curl http://localhost:8080/health
+# {"status":"ok"}
+```
+
+### WhatsApp Webhook Verification
+
+Meta sends a GET request to verify your webhook:
+
+```
+GET /webhook/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE
+```
+
+The server responds with the challenge if the verify token matches.
+
+### WhatsApp Message Webhook
+
+POST requests from WhatsApp are processed with:
+- **Rate limiting**: 120 requests/minute per client (sliding window)
+- **Idempotency**: Duplicate messages are ignored (5-minute TTL)
+- **Signature verification**: If `WHATSAPP_APP_SECRET` is set
+- **Request limits**: Max 64KB body, 30-second timeout
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes* | OpenAI API key |
+| `AZURE_OPENAI_API_KEY` | Yes* | Azure OpenAI API key |
+| `OPENAI_BASE_URL` | No | API base URL |
+| `OPENAI_MODEL` | No | Model name (default: gpt-4o-mini) |
+| `WHATSAPP_ACCESS_TOKEN` | For serve | WhatsApp API token |
+| `WHATSAPP_ENDPOINT_ID` | For serve | WhatsApp phone number ID |
+| `WHATSAPP_VERIFY_TOKEN` | For serve | Webhook verify token |
+| `WHATSAPP_APP_SECRET` | No | For signature verification |
+| `WHATSAPP_ALLOWED_NUMBERS` | No | Allowed phone numbers (comma-separated, or `*`) |
+
+*One of `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` is required for `run` command.
+
+### Using .env File
+
+Create a `.env` file in your working directory:
+
+```bash
+# .env
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini
+
+WHATSAPP_ACCESS_TOKEN=EAABc...
+WHATSAPP_ENDPOINT_ID=123456789012345
+WHATSAPP_VERIFY_TOKEN=my-secret-token
+WHATSAPP_APP_SECRET=abc123
+```
+
+## Examples
+
+### Run a Simple Query
+
+```bash
+OPENAI_API_KEY="sk-..." ./target/release/enact run --input "Hello!"
+```
+
+### Run with Custom Model
+
+```bash
+OPENAI_API_KEY="sk-..." \
+OPENAI_MODEL="gpt-4" \
+./target/release/enact run --input "Explain Rust ownership"
+```
+
+### Run with Azure OpenAI
+
+```bash
+AZURE_OPENAI_API_KEY="..." \
+OPENAI_BASE_URL="https://your-resource.openai.azure.com" \
+OPENAI_MODEL="gpt-4" \
+./target/release/enact run --input "Hello!"
+```
+
+### Start Gateway for Production
+
+```bash
+# Load from .env file
+source .env
+
+./target/release/enact serve --http-port 8080
+```
+
+### Air-Gapped Mode
+
+```bash
+OLLAMA_BASE_URL="http://localhost:11434" \
+OPENAI_MODEL="llama3" \
+./target/release/enact serve --http-port 8080 --air-gapped
+```
+
+## Roadmap
+
+### Phase 2 (Planned)
+- [ ] `enact init` - Create new agent project
+- [ ] `enact validate` - Validate YAML syntax
+- [ ] `enact console` - Interactive TUI
+
+### Phase 3 (Planned)
+- [ ] `enact deploy` - Deploy to channels
+- [ ] `enact logs` - View execution logs
+- [ ] `enact eval` - Run evaluation suites