enya-agent 0.1.0

package/docs/content/concepts/_index.md

@@ -0,0 +1,273 @@
++++
+title = "Concepts"
+weight = 5
+sort_by = "weight"
++++
+
+# Core Concepts
+
+Understanding Enact's architecture and design.
+
+## Architecture Overview
+
+Enact is built on a modular crate architecture:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          enact-cli                               │
+│              doctor │ run │ serve │ version                     │
+└───────────────────────────────┬─────────────────────────────────┘
+                                │
+┌───────────────────────────────▼─────────────────────────────────┐
+│                         enact-runner                             │
+│              DefaultAgentRunner │ LoopOutcome │ Retry           │
+└───────────────────────────────┬─────────────────────────────────┘
+                                │
+┌───────────────────────────────▼─────────────────────────────────┐
+│                          enact-core                              │
+│   LlmCallable │ Callable trait │ Graph System                   │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+    ┌───────────────┬───────────┼───────────┬───────────────┐
+    ▼               ▼           ▼           ▼               ▼
+┌─────────┐  ┌───────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
+│ skills  │  │ providers │  │ gateway │  │channels │  │   mcp   │
+│ TOML/MD │  │ OpenAI,   │  │  HTTP   │  │WhatsApp │  │  Stdio  │
+│ tools   │  │ Azure,etc │  │  Axum   │  │Telegram │  │JSON-RPC │
+└─────────┘  └───────────┘  └─────────┘  └─────────┘  └─────────┘
+```
+
+## Callable
+
+The `Callable` trait is the core abstraction for anything that can process input:
+
+```rust
+#[async_trait]
+pub trait Callable: Send + Sync {
+    fn name(&self) -> &str;
+    async fn run(&self, input: &str) -> anyhow::Result<String>;
+}
+```
+
+### LlmCallable
+
+LLM-powered callable with system prompt:
+
+```rust
+let callable = LlmCallable::with_provider(
+    "assistant",
+    "You are a helpful assistant.",
+    provider,
+);
+```
+
+## Runner
+
+The `DefaultAgentRunner` executes callables with production features:
+
+```rust
+let mut runner = DefaultAgentRunner::default_new();
+let outcome = runner.run(&callable, "Hello!").await?;
+```
+
+### LoopOutcome
+
+Execution results:
+
+```rust
+enum LoopOutcome {
+    Completed(String),                    // Success
+    MaxIterationsReached { last_output, iterations },
+    Cancelled,
+    TimedOut { elapsed_secs },
+}
+```
+
+## Gateway
+
+The HTTP gateway connects channels to the runner:
+
+```
+WhatsApp Message → WhatsAppChannel → RunnerResponder → DefaultAgentRunner → Response
+```
+
+### InboundResponder
+
+Custom message handling:
+
+```rust
+#[async_trait]
+pub trait InboundResponder: Send + Sync {
+    async fn handle(&self, message: &ChannelMessage) -> anyhow::Result<Option<String>>;
+}
+```
+
+Built-in implementations:
+- `EchoResponder` - Returns input as output
+- `RunnerResponder` - Routes through `DefaultAgentRunner`
+
+### Gateway Features
+
+| Feature | Description |
+|---------|-------------|
+| Rate Limiting | Sliding window, 120/min per client |
+| Idempotency | 5-minute TTL, SHA-256 deduplication |
+| Signature Verification | HMAC-SHA256 validation |
+| Request Limits | 64KB body, 30s timeout |
+
+## Channels
+
+Channels connect external messaging platforms:
+
+```rust
+#[async_trait]
+pub trait Channel: Send + Sync {
+    fn channel_id(&self) -> &str;
+    async fn receive(&self) -> Result<IncomingMessage>;
+    async fn send(&self, message: OutgoingMessage) -> Result<MessageId>;
+    async fn run(&self) -> Result<()>;
+}
+```
+
+### WhatsAppChannel
+
+```rust
+let channel = WhatsAppChannel::new(
+    access_token,
+    endpoint_id,
+    verify_token,
+    allowed_numbers,
+);
+```
+
+## Providers
+
+LLM providers implement `ModelProvider`:
+
+```rust
+#[async_trait]
+pub trait ModelProvider: Send + Sync {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse>;
+    fn requires_network(&self) -> bool { true }
+}
+```
+
+### OpenAICompatible
+
+Works with OpenAI, Azure, Ollama, OpenRouter:
+
+```rust
+let provider = OpenAICompatible::new(
+    "https://api.openai.com",
+    "gpt-4o-mini",
+    Some(api_key),
+);
+```
+
+## YAML Agent Schema
+
+Agents can be defined as YAML DAGs:
+
+```yaml
+name: my-agent
+version: "1.0"
+
+nodes:
+  process:
+    type: llm
+    system_prompt: "You are helpful."
+    edges:
+      _default: END
+```
+
+### Node Types
+
+| Type | Description |
+|------|-------------|
+| `llm` | LLM processing with system prompt |
+| `function` | Execute shell command |
+| `condition` | Branch based on expression |
+| `graph` | Execute sub-graph |
+
+## Configuration
+
+Environment-based configuration:
+
+```bash
+# LLM Provider
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_BASE_URL=https://api.openai.com
+
+# WhatsApp
+WHATSAPP_ACCESS_TOKEN=...
+WHATSAPP_ENDPOINT_ID=...
+WHATSAPP_VERIFY_TOKEN=...
+```
+
+## Skills System
+
+Skills are user-defined or community-built capabilities. They live in `~/.enact/skills/<name>/` or in your workspace `skills/` directory.
+
+### Skill Formats
+
+**SKILL.toml** - Structured format with tools:
+
+```toml
+[skill]
+name = "my-skill"
+description = "What this skill does"
+version = "0.1.0"
+author = "your-name"
+tags = ["productivity", "automation"]
+
+[[tools]]
+name = "my_tool"
+description = "What this tool does"
+kind = "shell"
+command = "echo hello"
+```
+
+**SKILL.md** - Simple markdown with instructions for the agent.
+
+### Open-Skills Integration
+
+Enact automatically syncs with the [open-skills](https://github.com/besoeasy/open-skills) community repository.
+
+## MCP Client
+
+The Model Context Protocol (MCP) client connects to MCP servers via stdio transport.
+
+### Connecting to an MCP Server
+
+```rust
+use enact_mcp::McpStdioClient;
+
+let mut client = McpStdioClient::new("mcp-server", &["--arg"]).await?;
+
+// List available tools
+let tools = client.list_tools().await?;
+
+// Call a tool
+let result = client.call_tool("tool_name", json!({"arg": "value"})).await?;
+```
+
+### MCP Features
+
+- **JSON-RPC 2.0 protocol**
+- **Stdio transport** (subprocess communication)
+- **Tool discovery** via `tools/list`
+- **Tool execution** via `tools/call`
+- **Async/await support**
+
+## Future Concepts
+
+### OAuth Token Lifecycle (Phase 1)
+- Token management
+- Automatic refresh
+- Secure storage
+
+### Multi-Agent (Phase 2)
+- Agent communication
+- Orchestration
+- Shared state

package/docs/content/configuration/_index.md

@@ -0,0 +1,241 @@
++++
+title = "Configuration"
+weight = 4
+sort_by = "weight"
++++
+
+# Configuration
+
+Enact configuration via environment variables and `.env` files.
+
+## Status
+
+| Feature | Status |
+|---------|--------|
+| `.env` file loading | ✅ Implemented |
+| Environment variables | ✅ Implemented |
+| Config struct | ✅ Implemented |
+| CLI config commands | 🚧 Future |
+| Encrypted settings | 🚧 Future |
+| Config TUI | 🚧 Future |
+
+## Quick Start
+
+Create a `.env` file in your project root:
+
+```bash
+# .env
+OPENAI_API_KEY=sk-...
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+```
+
+Load configuration in Rust:
+
+```rust
+use enact_config::Config;
+
+let config = Config::load()?;
+let api_key = config.openai_api_key()?;
+```
+
+## Environment Variables
+
+### LLM Providers
+
+```bash
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=your-key
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-4
+AZURE_OPENAI_API_VERSION=2024-02-01
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+OPENAI_ORG_ID=org-...  # Optional
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Google
+GOOGLE_API_KEY=...
+
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-...
+
+# Ollama (local)
+OLLAMA_ENDPOINT=http://localhost:11434
+```
+
+### Channels
+
+```bash
+# Telegram
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+
+# Teams
+TEAMS_APP_ID=your-azure-ad-app-id
+TEAMS_APP_SECRET=your-client-secret
+TEAMS_TENANT_ID=your-tenant-id  # or "common" for multi-tenant
+
+# WhatsApp
+WHATSAPP_PHONE_NUMBER_ID=123456789012345
+WHATSAPP_ACCESS_TOKEN=EAABc...
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-secret-token
+WHATSAPP_APP_SECRET=your-app-secret  # Optional, for signature verification
+```
+
+## Using Configuration
+
+### In Rust Code
+
+```rust
+use enact_config::Config;
+use enact_providers::azure::AzureOpenAiProvider;
+
+// Load config from .env and environment
+let config = Config::load()?;
+
+// Create provider from config
+let provider = AzureOpenAiProvider::from_config(&config)?;
+```
+
+### Config Struct
+
+```rust
+pub struct Config {
+    // Azure OpenAI
+    pub azure_openai_api_key: Option<String>,
+    pub azure_openai_endpoint: Option<String>,
+    pub azure_openai_deployment: Option<String>,
+    pub azure_openai_api_version: Option<String>,
+
+    // OpenAI
+    pub openai_api_key: Option<String>,
+    pub openai_org_id: Option<String>,
+
+    // Anthropic
+    pub anthropic_api_key: Option<String>,
+
+    // Google
+    pub google_api_key: Option<String>,
+
+    // OpenRouter
+    pub openrouter_api_key: Option<String>,
+
+    // Ollama
+    pub ollama_endpoint: Option<String>,
+
+    // Telegram
+    pub telegram_bot_token: Option<String>,
+
+    // Teams
+    pub teams_app_id: Option<String>,
+    pub teams_app_secret: Option<String>,
+    pub teams_tenant_id: Option<String>,
+
+    // WhatsApp
+    pub whatsapp_phone_number_id: Option<String>,
+    pub whatsapp_access_token: Option<String>,
+    pub whatsapp_webhook_verify_token: Option<String>,
+    pub whatsapp_app_secret: Option<String>,
+}
+```
+
+## Configuration Priority
+
+Configuration values are loaded in this order (later overrides earlier):
+
+1. Default values
+2. `.env` file in current directory
+3. Environment variables
+
+```bash
+# Environment variable overrides .env file
+export OPENAI_API_KEY=sk-override...
+```
+
+## Security Best Practices
+
+### Never Commit Secrets
+
+Add `.env` to `.gitignore`:
+
+```bash
+# .gitignore
+.env
+.env.local
+.env.*.local
+```
+
+### Use Different Keys per Environment
+
+```bash
+# .env.development
+OPENAI_API_KEY=sk-dev-...
+
+# .env.production
+OPENAI_API_KEY=sk-prod-...
+```
+
+### Validate Required Config
+
+```rust
+let config = Config::load()?;
+
+// These will error if not set
+let api_key = config.openai_api_key()
+    .ok_or_else(|| anyhow::anyhow!("OPENAI_API_KEY not set"))?;
+```
+
+---
+
+## Future Configuration (🚧 Planned)
+
+### CLI Config Commands (🚧 Future)
+
+```bash
+# Open interactive configuration TUI
+enact config
+
+# Or set values via CLI
+enact config set runtime.mode local
+enact config get runtime.mode
+```
+
+### Encrypted Settings (🚧 Future)
+
+Non-sensitive settings will be stored encrypted:
+
+```bash
+enact config set runtime.stepTimeoutMs 30000
+enact config set storage.vectorStore.type qdrant
+```
+
+Storage location (planned):
+- macOS: `~/.config/enact/config.encrypted`
+- Linux: `~/.config/enact/config.encrypted`
+- Windows: `%APPDATA%\enact\config.encrypted`
+
+### Runtime Modes (🚧 Future)
+
+| Mode | Network | Cloud Sync | Use Case |
+|------|---------|------------|----------|
+| `local` | ✅ Full | ❌ Off | Development, personal use |
+| `airgapped` | ❌ Blocked | ❌ Off | Enterprise, secure environments |
+| `cloud` | ✅ Full | ✅ On | Team collaboration |
+
+```bash
+# Set mode (Future)
+enact config set runtime.mode airgapped
+
+# Or via CLI flag (Future)
+enact serve --air-gapped
+```
+
+### Air-Gapped Mode (🚧 Future)
+
+When `runtime.mode = airgapped`:
+- All outbound network calls are blocked
+- Only local features available (Ollama, local storage)
+- Telemetry exporters are disabled
+- Cloud sync is disabled