enya-agent 0.1.0

package/docs/content/troubleshooting/_index.md

@@ -0,0 +1,259 @@
++++
+title = "Troubleshooting"
+weight = 7
+sort_by = "weight"
++++
+
+# Troubleshooting
+
+Common issues and how to fix them.
+
+## Build Issues
+
+### Rust Version Too Old
+
+**Error:** "edition 2021 is not supported"
+
+**Fix:**
+```bash
+# Update Rust
+rustup update stable
+
+# Verify version (need 1.75+)
+rustc --version
+```
+
+### Missing Dependencies
+
+**Error:** "failed to find OpenSSL"
+
+**Fix:**
+```bash
+# macOS
+brew install openssl
+
+# Ubuntu/Debian
+sudo apt-get install libssl-dev pkg-config
+
+# Fedora
+sudo dnf install openssl-devel
+```
+
+### Cargo Build Fails
+
+**Error:** "failed to compile"
+
+**Fix:**
+```bash
+# Clean and rebuild
+cargo clean
+cargo build --release
+
+# Check for specific crate issues
+cargo build -p enact-core
+```
+
+## Configuration Issues
+
+### "No API key found"
+
+Enact can't find your LLM provider credentials.
+
+**Fix:**
+```bash
+# Check .env file exists and contains the key
+cat .env | grep API_KEY
+
+# Verify environment variable is set
+echo $OPENAI_API_KEY
+
+# Create or update .env file
+echo "OPENAI_API_KEY=sk-..." >> .env
+```
+
+### Wrong API Key Format
+
+**Error:** "Invalid API key"
+
+**Common issues:**
+- Extra whitespace in key
+- Missing prefix (e.g., `sk-` for OpenAI)
+- Wrong key for wrong provider
+
+**Fix:**
+```bash
+# Ensure no trailing whitespace
+OPENAI_API_KEY=sk-abc123  # No spaces after
+
+# Verify correct provider
+# OpenAI keys start with: sk-
+# Anthropic keys start with: sk-ant-
+# Azure keys are UUIDs
+```
+
+## Provider Issues
+
+### Rate Limited
+
+**Error:** "rate_limit_exceeded"
+
+**Fix:**
+- Wait and retry (usually 60 seconds)
+- Use a different model
+- Check your provider's rate limit documentation
+- Consider using multiple API keys
+
+### Network Errors
+
+**Error:** "Connection refused" or "timeout"
+
+**Fix:**
+```bash
+# Check network connectivity
+curl -I https://api.openai.com
+
+# Check for proxy issues
+echo $HTTP_PROXY
+echo $HTTPS_PROXY
+
+# For Ollama, verify it's running
+curl http://localhost:11434/api/tags
+```
+
+### Invalid Response
+
+**Error:** "Failed to parse response"
+
+**Causes:**
+- Provider API changed
+- Network returned error page
+- Proxy intercepting traffic
+
+**Fix:**
+- Check provider status page
+- Update to latest Enact version
+- Check for corporate proxy/firewall
+
+## Channel Issues
+
+### Telegram Bot Not Responding
+
+**Checklist:**
+1. Bot token is correct
+2. User has started the bot (`/start`)
+3. Application is running
+4. Check logs for errors
+
+**Debug:**
+```bash
+# Test token directly
+curl "https://api.telegram.org/bot<TOKEN>/getMe"
+
+# Should return:
+# {"ok":true,"result":{"id":123...,"is_bot":true,...}}
+```
+
+### Teams Messages Not Delivered
+
+**Checklist:**
+1. App is registered in Azure AD
+2. App is published to Teams
+3. Webhook URL is accessible (if using webhooks)
+4. SSL certificate is valid
+
+### WhatsApp Webhook Errors
+
+**Checklist:**
+1. Webhook URL uses HTTPS
+2. Verify token matches configuration
+3. App is in Live mode (not Development)
+4. Phone number is registered with Meta Business
+
+## Graph/Agent Issues
+
+### YAML Parse Error
+
+**Error:** "Failed to parse YAML"
+
+**Fix:**
+```yaml
+# Check YAML syntax
+# Common issues:
+# - Wrong indentation (use spaces, not tabs)
+# - Missing quotes around special values
+# - Invalid characters
+
+# Use a YAML validator
+# https://www.yamllint.com/
+```
+
+### Node Not Found
+
+**Error:** "Node 'xyz' not found"
+
+**Fix:**
+- Check node name spelling in edges
+- Ensure node is defined in `nodes:` section
+- Use `END` (uppercase) for termination
+
+### Infinite Loop
+
+**Symptoms:** Agent keeps running, never terminates
+
+**Fix:**
+- Check edges don't create cycles
+- Ensure at least one path leads to `END`
+- Add `_default: END` edge as fallback
+
+## Performance Issues
+
+### Slow Compilation
+
+**Fix:**
+```bash
+# Use incremental builds
+cargo build  # (not --release for dev)
+
+# Use sccache for caching
+cargo install sccache
+export RUSTC_WRAPPER=sccache
+```
+
+### High Memory Usage
+
+**Fix:**
+- Reduce graph complexity
+- Use smaller models
+- Process in batches
+
+## Debugging
+
+### Enable Verbose Logging
+
+```bash
+# Set log level
+RUST_LOG=debug cargo run
+
+# Or specific modules
+RUST_LOG=enact_core=trace,enact_providers=debug cargo run
+```
+
+### Check Library Versions
+
+```bash
+# Show dependency tree
+cargo tree -p enact-core
+
+# Check for conflicts
+cargo tree -d
+```
+
+## Getting Help
+
+- Check the [documentation](/)
+- Search [GitHub Issues](https://github.com/your-org/enact-agent/issues)
+- Open a new issue with:
+  - Rust version (`rustc --version`)
+  - OS and version
+  - Error message and stack trace
+  - Minimal reproduction steps

package/docs/content/yaml-schema/_index.md

@@ -0,0 +1,294 @@
++++
+title = "YAML Schema"
+weight = 4
+sort_by = "weight"
++++
+
+# YAML Agent Schema
+
+Enact agents are defined using YAML files. This page documents the complete schema.
+
+## Overview
+
+```yaml
+name: string           # Required: Agent name
+version: string        # Optional: Version (default: "1.0")
+description: string    # Optional: Description
+triggers: [string]     # Optional: Trigger types
+inputs: {key: desc}    # Optional: Expected inputs
+nodes: {name: node}    # Required: Node definitions
+```
+
+## Complete Example
+
+```yaml
+name: research-assistant
+version: "1.0"
+description: "Researches topics and provides summaries"
+
+triggers:
+  - manual
+  - "cron:0 9 * * *"  # Daily at 9am
+
+inputs:
+  topic: "Research topic"
+  depth: "shallow or deep"
+
+nodes:
+  gather:
+    type: llm
+    model: gpt-4
+    system_prompt: |
+      You are a research assistant. Search for information about the topic.
+      Be thorough and cite sources.
+    tools:
+      - web_search
+    edges:
+      _default: analyze
+
+  analyze:
+    type: llm
+    system_prompt: "Analyze the gathered information for key insights."
+    edges:
+      _default: check_quality
+
+  check_quality:
+    type: condition
+    expr: "output.length > 500"
+    edges:
+      "true": summarize
+      "false": gather  # Loop back for more research
+      _default: summarize
+
+  summarize:
+    type: llm
+    system_prompt: "Create a concise executive summary."
+    edges:
+      _default: END
+```
+
+## Node Types
+
+### LLM Node
+
+Execute an LLM with a system prompt and optional tools.
+
+```yaml
+node_name:
+  type: llm
+  model: string              # Optional: Model name (e.g., "gpt-4")
+  system_prompt: string      # Required: System prompt
+  tools: [string]            # Optional: Tool names to enable
+  edges:
+    _default: next_node      # Required: Default next node
+    key: target_node         # Optional: Conditional edges
+```
+
+**Example:**
+
+```yaml
+analyst:
+  type: llm
+  model: claude-3-opus
+  system_prompt: |
+    You are a financial analyst. Analyze the provided data
+    and identify trends, risks, and opportunities.
+  tools:
+    - calculator
+    - chart_generator
+  edges:
+    _default: report
+```
+
+### Function Node
+
+Execute a shell command or script.
+
+```yaml
+node_name:
+  type: function
+  action: string             # Required: Shell command
+  edges:
+    _default: next_node
+```
+
+**Example:**
+
+```yaml
+run_tests:
+  type: function
+  action: "npm test -- --coverage"
+  edges:
+    _default: check_coverage
+
+build:
+  type: function
+  action: "cargo build --release"
+  edges:
+    _default: deploy
+```
+
+### Condition Node
+
+Branch execution based on an expression.
+
+```yaml
+node_name:
+  type: condition
+  expr: string               # Required: Expression to evaluate
+  edges:
+    "true": node_if_true     # Edge if expression is true
+    "false": node_if_false   # Edge if expression is false
+    _default: fallback_node  # Fallback edge
+```
+
+**Example:**
+
+```yaml
+check_errors:
+  type: condition
+  expr: "input.contains('error')"
+  edges:
+    "true": handle_error
+    "false": continue
+    _default: continue
+
+check_score:
+  type: condition
+  expr: "score > 80"
+  edges:
+    "true": approve
+    "false": request_review
+```
+
+### Graph Node
+
+Execute another graph as a sub-workflow.
+
+```yaml
+node_name:
+  type: graph
+  graph_name: string         # Required: Name of sub-graph to execute
+  edges:
+    _default: next_node
+```
+
+**Example:**
+
+```yaml
+detailed_review:
+  type: graph
+  graph_name: code-review-detailed
+  edges:
+    _default: summarize
+```
+
+## Edge Routing
+
+### Default Edge
+
+Every node must have a `_default` edge:
+
+```yaml
+edges:
+  _default: next_node   # Go to next_node
+  _default: END         # End execution
+```
+
+### Conditional Edges
+
+Nodes can have multiple edges based on output:
+
+```yaml
+edges:
+  "success": celebrate
+  "failure": retry
+  "error": handle_error
+  _default: fallback
+```
+
+### Special Target: END
+
+Use `END` to terminate the graph:
+
+```yaml
+edges:
+  _default: END
+```
+
+## Triggers (🚧 Future)
+
+Define how the agent can be invoked:
+
+```yaml
+triggers:
+  - manual                    # Manual invocation
+  - "cron:0 9 * * *"         # Cron schedule
+  - "webhook:/api/trigger"   # HTTP webhook
+  - "channel:telegram"       # Channel message
+```
+
+## Inputs
+
+Define expected inputs with descriptions:
+
+```yaml
+inputs:
+  query: "The user's question"
+  context: "Optional context"
+  max_tokens: "Maximum response length"
+```
+
+## Tools (🚧 Partial)
+
+Available tools for LLM nodes:
+
+| Tool | Description | Status |
+|------|-------------|--------|
+| `web_search` | Search the web | 🚧 Future |
+| `file_read` | Read local files | 🚧 Future |
+| `file_write` | Write local files | 🚧 Future |
+| `calculator` | Math operations | 🚧 Future |
+| `code_exec` | Execute code | 🚧 Future |
+
+## Validation
+
+The YAML loader validates:
+
+- ✅ Required fields present
+- ✅ Node types are valid
+- ✅ Edge targets exist
+- ✅ No cycles in graph (DAG invariant)
+- ✅ Entry point exists
+
+**Error examples:**
+
+```
+Error: Edge target 'nonexistent' does not exist
+Error: Graph contains a cycle: A -> B -> C -> A
+Error: No entry point defined
+```
+
+## Loading Graphs
+
+### Rust API
+
+```rust
+use enact_core::graph::GraphLoader;
+
+// From string
+let graph = GraphLoader::load_from_str(yaml_content)?;
+
+// Compile for execution
+let compiled = graph.compile()?;
+```
+
+### 🚧 CLI (Future)
+
+```bash
+# Validate YAML
+enact validate agent.yaml
+
+# Run agent
+enact run --agent agent.yaml --input "Hello"
+```

package/docs/static/giallo-dark.css

@@ -0,0 +1,91 @@
+/*
+ * theme "github-dark" generated by giallo
+ */
+
+.z-code {
+  color: #E1E4E8;
+  background-color: #24292E;
+}
+
+.z-hl {
+  background-color: #2B3036;
+}
+
+.giallo-ln {
+  color: #444D56;
+}
+
+.z-comment { color: #6A737D; }
+.z-constant { color: #79B8FF; }
+.z-entity { color: #B392F0; }
+.z-keyword { color: #F97583; }
+.z-storage { color: #F97583; }
+.z-string { color: #9ECBFF; }
+.z-support { color: #79B8FF; }
+.z-variable { color: #FFAB70; }
+.z-carriage-return { color: #24292E; background-color: #F97583; font-style: italic;text-decoration: underline; }
+.z-variable { color: #79B8FF; }
+.z-source { color: #9ECBFF; }
+.z-string.z-comment { color: #6A737D; }
+.z-variable.z-language { color: #79B8FF; }
+.z-entity.z-name { color: #B392F0; }
+.z-storage.z-type { color: #F97583; }
+.z-meta.z-property-name { color: #79B8FF; }
+.z-variable.z-other { color: #E1E4E8; }
+.z-invalid.z-broken { color: #FDAEB7; font-style: italic; }
+.z-invalid.z-deprecated { color: #FDAEB7; font-style: italic; }
+.z-invalid.z-illegal { color: #FDAEB7; font-style: italic; }
+.z-invalid.z-unimplemented { color: #FDAEB7; font-style: italic; }
+.z-message.z-error { color: #FDAEB7; }
+.z-source.z-regexp { color: #DBEDFF; }
+.z-string.z-regexp { color: #DBEDFF; }
+.z-support.z-constant { color: #79B8FF; }
+.z-support.z-variable { color: #79B8FF; }
+.z-meta.z-module-reference { color: #79B8FF; }
+.z-markup.z-heading { color: #79B8FF; font-weight: bold; }
+.z-markup.z-quote { color: #85E89D; }
+.z-markup.z-italic { color: #E1E4E8; font-style: italic; }
+.z-markup.z-bold { color: #E1E4E8; font-weight: bold; }
+.z-markup.z-underline { text-decoration: underline; }
+.z-markup.z-strikethrough { text-decoration: line-through; }
+.z-markup.z-deleted { color: #FDAEB7; background-color: #86181D; }
+.z-markup.z-inserted { color: #85E89D; background-color: #144620; }
+.z-markup.z-changed { color: #FFAB70; background-color: #C24E00; }
+.z-markup.z-ignored { color: #2F363D; background-color: #79B8FF; }
+.z-markup.z-untracked { color: #2F363D; background-color: #79B8FF; }
+.z-meta.z-separator { color: #79B8FF; font-weight: bold; }
+.z-meta.z-output { color: #79B8FF; }
+.z-brackethighlighter.z-tag { color: #D1D5DA; }
+.z-brackethighlighter.z-curly { color: #D1D5DA; }
+.z-brackethighlighter.z-round { color: #D1D5DA; }
+.z-brackethighlighter.z-square { color: #D1D5DA; }
+.z-brackethighlighter.z-angle { color: #D1D5DA; }
+.z-brackethighlighter.z-quote { color: #D1D5DA; }
+.z-brackethighlighter.z-unmatched { color: #FDAEB7; }
+.z-entity.z-name { color: #79B8FF; font-weight: bold; }
+.z-punctuation.z-definition.z-comment { color: #6A737D; }
+.z-entity.z-name.z-constant { color: #79B8FF; }
+.z-variable.z-other.z-constant { color: #79B8FF; }
+.z-variable.z-other.z-enummember { color: #79B8FF; }
+.z-variable.z-parameter.z-function { color: #E1E4E8; }
+.z-entity.z-name.z-tag { color: #85E89D; }
+.z-storage.z-modifier.z-package { color: #E1E4E8; }
+.z-storage.z-modifier.z-import { color: #E1E4E8; }
+.z-storage.z-type.z-java { color: #E1E4E8; }
+.z-punctuation.z-definition.z-string { color: #9ECBFF; }
+.z-string.z-regexp.z-character-class { color: #DBEDFF; }
+.z-markup.z-inline.z-raw { color: #79B8FF; }
+.z-punctuation.z-definition.z-deleted { color: #FDAEB7; background-color: #86181D; }
+.z-punctuation.z-definition.z-inserted { color: #85E89D; background-color: #144620; }
+.z-punctuation.z-definition.z-changed { color: #FFAB70; background-color: #C24E00; }
+.z-meta.z-diff.z-range { color: #B392F0; font-weight: bold; }
+.z-meta.z-diff.z-header { color: #79B8FF; }
+.z-string.z-other.z-link { color: #DBEDFF; text-decoration: underline; }
+.z-constant.z-character.z-escape { color: #DBEDFF; }
+.z-source.z-ruby.z-embedded { color: #DBEDFF; }
+.z-string.z-regexp.z-arbitrary-repitition { color: #DBEDFF; }
+.z-constant.z-character.z-escape { color: #85E89D; font-weight: bold; }
+.z-meta.z-diff.z-header.z-from-file { color: #FDAEB7; background-color: #86181D; }
+.z-meta.z-diff.z-header.z-to-file { color: #85E89D; background-color: #144620; }
+.z-constant.z-other.z-reference.z-link { color: #DBEDFF; text-decoration: underline; }
+.z-punctuation.z-definition.z-list.z-begin.z-markdown { color: #FFAB70; }