legate 0.1.0

data/public/docs/examples.md

@@ -0,0 +1,199 @@
+# Examples Guide
+
+Legate ships with a curated set of examples that walk you through every major feature of the framework. Each example is self-contained and can be run directly from the project root.
+
+```bash
+bundle exec ruby examples/01_simple_agent.rb
+```
+
+> **Note:** Examples that call the Gemini LLM require a `GOOGLE_API_KEY` environment variable. See `.env.example` for the full list.
+
+---
+
+## Core Examples
+
+These numbered examples form a progressive learning path — start at 00 (the `agent.ask` quickstart) and work your way up.
+
+### Getting Started
+
+#### 00 — Quickstart (`agent.ask`)
+`examples/00_quickstart.rb`
+
+The shortest path: define an agent and get an answer with `agent.ask('…').answer`. Shows the `Event` result accessors (`#answer` / `#success?` / `#error_message`), streaming progress via a block, and how to continue a conversation with `session_id:`. Start here.
+
+#### 01 — Simple Agent
+`examples/01_simple_agent.rb`
+
+The "hello world" of Legate using the **explicit** lifecycle that `ask` automates: define → instantiate → start → run_task → stop, with a single agent and the built-in Echo tool. Reach for this when you need fine control over sessions and lifecycle.
+
+#### 02 — Multi-Tool Agent
+`examples/02_multi_tool_agent.rb`
+
+Registers multiple tools (Echo, Calculator, CatFacts, RandomNumber) on a single agent and demonstrates how the Gemini planner selects the appropriate tool for each request. Also shows agent-to-agent delegation via the built-in `delegate_task` tool.
+
+#### 03 — Custom Tool
+`examples/03_custom_tool.rb`
+
+How to build your own tool from scratch using the `Legate::Tool` DSL. Defines parameters with types, implements `perform_execution`, registers the tool globally, uses it both directly and through an agent.
+
+### Core Patterns
+
+#### 04 — Agent Instructions
+`examples/04_agent_instructions.rb`
+
+Shows how the `instruction` field acts as a system prompt that guides the planner's behavior. Runs two tasks against the same agent — one that fits the instructions and one that doesn't — to demonstrate how instructions shape agent responses.
+
+#### 05 — State & Sessions
+`examples/05_state_and_sessions.rb`
+
+Demonstrates session state management: creating sessions with initial state, reading and writing state from tools via `ToolContext`, scoped state keys (`user:`, `app:`, `temp:`), and inspecting event history after task execution.
+
+#### 06 — Callbacks
+`examples/06_callbacks.rb`
+
+Registers all six lifecycle callbacks (`before_agent`, `after_agent`, `before_model`, `after_model`, `before_tool`, `after_tool`) on an agent and logs each invocation. Shows how callbacks can inspect and pass through context, prompts, and tool parameters.
+
+### Async & Jobs
+
+#### 07 — Async Jobs
+`examples/07_async_jobs.rb`
+
+Uses the `SleepyTool` (a `BaseAsyncJobTool` subclass) to start a background job, then checks its status with `check_job_status`. Demonstrates the `:pending` → `:success` lifecycle for long-running operations.
+
+### Multi-Agent Systems
+
+#### 08 — Loop Agent
+`examples/08_loop_agent.rb`
+
+Creates a `LoopAgent` that runs sub-agents in a cycle until a termination condition is met (or max iterations are reached). Uses a counter agent and a condition-checking agent to demonstrate state-driven loop control.
+
+#### 09 — Sequential Workflow
+`examples/09_sequential_workflow.rb`
+
+Defines a pipeline of three agents (data gatherer → data processor → report writer) that execute in order using the `:sequential` agent type. Each agent stores its output via `output_key` for the next agent to consume.
+
+#### 10 — Parallel Workflow
+`examples/10_parallel_workflow.rb`
+
+Defines two analyst agents that run concurrently using the `:parallel` agent type. Shows how to fan out work across multiple agents and merge their results.
+
+#### 11 — Agent Delegation
+`examples/11_agent_delegation.rb`
+
+Sets up a manager agent that can delegate math problems to a specialist agent using `can_delegate_to`. Demonstrates the agent hierarchy and task handoff pattern.
+
+### Integration
+
+#### 12 — HTTP Client Tool
+`examples/12_http_client_tool.rb`
+
+Builds a complete HTTP API tool using the `Legate::Tools::Base::HttpClient` mixin. Connects to JSONPlaceholder to demonstrate GET and POST requests, JSON parsing, and error handling for missing parameters and invalid actions.
+
+#### 13 — Authentication
+`examples/13_authentication.rb`
+
+Covers HTTP Bearer authentication end-to-end: creating credentials, exchanging tokens, applying auth to requests, using the Excon middleware, and integrating auth into a custom tool. Uses httpbin.org for live verification.
+
+#### 14 — MCP Client
+`examples/14_mcp_client.rb`
+
+Configures an agent to connect to an external MCP server (the `@modelcontextprotocol/server-filesystem` package) via stdio. Shows MCP server configuration, tool discovery, and running tasks that use external MCP tools alongside native Legate tools.
+
+#### 15 — MCP Server
+`examples/15_mcp_server.rb`
+
+Wraps the built-in Calculator tool using `LegateToolAdapter` and exposes it on a `fast-mcp` STDIO server. Demonstrates how to make any Legate tool available to external MCP clients.
+
+#### 16 — Webhooks
+`examples/16_webhooks.rb`
+
+Sends an HMAC-signed webhook payload to an external URL using the built-in `WebhookTool`. Uses [webhook.site](https://webhook.site) for easy testing. Demonstrates HMAC-SHA256 payload signing, custom headers, and delivery verification.
+
+---
+
+## Advanced Examples
+
+The `examples/advanced/` directory contains deeper explorations of specific subsystems. These are useful as reference but assume familiarity with the core examples above.
+
+### Authentication (`advanced/auth/`)
+
+In-depth authentication patterns beyond the basics in example 13:
+
+| File | Description |
+|------|-------------|
+| `oauth2_auth.rb` | Full OAuth 2.0 authorization code flow |
+| `oidc_auth.rb` | OpenID Connect authentication |
+| `service_account.rb` | Service account / client credentials flow |
+| `fiber_auth_example.rb` | Non-blocking auth using Ruby Fibers |
+| `fiber_oidc_example.rb` | Fiber-based OIDC flow |
+| `token_lifecycle_example.rb` | Token refresh, expiry, and lifecycle management |
+| `cookie_auth_tool.rb` | Cookie-based authentication |
+| `excon_middleware.rb` | Custom Excon middleware for auth |
+| `excon_middleware_auth.rb` | Auth-specific Excon middleware |
+| `httpbin_bearer_tool.rb` | Bearer auth against httpbin.org |
+| `openweather_api.rb` | Real-world API key auth (OpenWeather) |
+| `openweather_tool.rb` | Tool wrapping the OpenWeather API |
+| `query_param_middleware_test.rb` | Query parameter auth scheme |
+| `test_with_httpbin.rb` | Auth integration testing with httpbin |
+| `custom_auth_flows_example.rb` | Building custom auth schemes |
+
+### Multi-Agent Systems (`advanced/mas/`)
+
+Additional orchestration patterns beyond examples 08–11:
+
+| File | Description |
+|------|-------------|
+| `fixed_delegation_example.rb` | Delegation with explicit agent routing |
+| `proper_delegation_example.rb` | Production-style delegation patterns |
+| `loop_workflow.rb` | Loop agent in a workflow context |
+| `mock_planner.rb` | Testing agents with a mock planner |
+
+### MCP (`advanced/mcp/`)
+
+Additional MCP server configurations beyond examples 14–15:
+
+| File | Description |
+|------|-------------|
+| `mcp_server_rack.rb` | MCP server running on Rack |
+| `mcp_server_async.rb` | Async MCP server |
+| `mcp_server_async_tools.rb` | MCP server with async tool execution |
+| `mcp_server_legate_agent.rb` | Expose a full agent (not just a tool) via MCP |
+| `mcp_resource_server_example.rb` | MCP server with resource discovery |
+| `legate_mcp_server_resource_example.rb` | Resource handling in MCP servers |
+
+### Webhooks (`advanced/webhooks/`)
+
+End-to-end webhook patterns beyond example 16:
+
+| File | Description |
+|------|-------------|
+| `webhook_receiver_agent.rb` | Agent that listens for incoming webhooks |
+| `webhook_e2e_runner.rb` | End-to-end webhook sender + receiver test |
+
+### Workflows (`advanced/workflows/`)
+
+Complex multi-agent workflow examples:
+
+| File | Description |
+|------|-------------|
+| `travel_planner_sequential.rb` | 4-agent sequential travel planner with TTY spinners |
+| `travel_planner_parallel.rb` | Travel planner with parallel research agents |
+| `travel_planner_auto_sequential.rb` | Auto-wired sequential travel planner |
+| `task_refinement_loop_agent.rb` | Iterative text refinement using a 3-agent loop |
+
+### Other (`advanced/`)
+
+| File | Description |
+|------|-------------|
+| `callback_monitoring.rb` | Production-style monitoring with callbacks (metrics, timers, content filtering) |
+| `random_calculator.rb` | Multi-step planning with random numbers and calculator |
+| `sleep_agent.rb` | Async job agent with manual polling |
+
+---
+
+## Support Files
+
+The `examples/tools/` directory contains shared tool definitions used by the examples:
+
+- `sleepy_tool.rb` — A `BaseAsyncJobTool` subclass that simulates long-running work (used by examples 07 and the advanced sleep agent)
+- `oauth2_example.rb` — OAuth2 tool helper for auth examples

data/public/docs/getting_started.md

@@ -0,0 +1,111 @@
+# Getting Started with Legate
+
+This guide will walk you through setting up your first Legate project using the `skaffold` command.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+*   **Ruby** (version 3.4 or higher is required)
+*   **Bundler** (`gem install bundler`)
+
+## 1. Install the Legate Gem
+
+First, install the `legate` gem globally or add it to your Gemfile.
+
+```bash
+gem install legate
+```
+
+## 2. Create a New Project
+
+The easiest way to start is by using the `skaffold` command. This will generate a complete directory structure with sample files.
+
+```bash
+legate skaffold my-awesome-agent
+```
+
+This will create a directory named `my-awesome-agent` with the following structure:
+
+*   `Gemfile`: Dependency definitions.
+*   `config.ru`: Configuration for running the Legate Web UI.
+*   `agents/`: Directory for your agent definitions.
+    *   `hello_world_agent.rb`: A simple sample agent that uses the sample tool.
+*   `tools/`: Directory for custom tools.
+    *   `sample_tool.rb`: A sample tool implementation.
+*   `.env.example`: Template for environment variables.
+*   `bin/`: Helper scripts.
+    *   `console`: Starts an IRB console with your agents loaded.
+
+## 3. Configure Your Environment
+
+Navigate into your new project directory:
+
+```bash
+cd my-awesome-agent
+```
+
+Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and add your configuration, specifically your `GOOGLE_API_KEY` if you plan to use Gemini models.
+
+```bash
+GOOGLE_API_KEY=your_actual_api_key_here
+```
+
+## 4. Install Dependencies
+
+Run Bundler to install the required gems:
+
+```bash
+bundle install
+```
+
+## 5. Run the Application
+
+You can now start the Legate Web UI to interact with your agents.
+
+```bash
+bundle exec legate web start
+```
+
+By default, this starts the server at `http://localhost:4567` (override with `--port`). Open this URL in your browser to see the Legate dashboard.
+
+## 6. Interact with Your Agent
+
+**From the Web UI:**
+
+1.  In the Web UI, go to the "Agents" tab.
+2.  You should see the `hello_world` agent.
+3.  Click "Start Chat" (or similar).
+4.  Type "Say hello!" and see the agent respond.
+
+**From Ruby code** — the quickest path is `Agent#ask`, which starts the agent,
+runs the task, and returns the final event:
+
+```ruby
+require 'legate'
+
+agent = Legate::Agent.new(definition: Legate::AgentDefinition.new.define do |a|
+  a.name :hello_world
+  a.description 'Greets the user.'
+  a.instruction 'Say hello back to the user.'
+  a.use_tool :echo
+end)
+
+puts agent.ask('Say hello!').answer
+```
+
+Call `.answer` for the result, or `.success?` / `.error_message` to branch on the
+outcome. Pass `session_id:` to continue a conversation, and a block to watch
+progress live (`agent.ask('…') { |event| ... }`).
+
+## Next Steps
+
+*   **Create more agents:** Use `legate agent generate my_new_agent` to create more agents.
+*   **Learn about Tools:** Check out the [Built-in Tools Reference](./tools/legate_built_in_tools) to see what tools are available.
+*   **Deploy:** When you're ready, use `legate deployment generate` to prepare for cloud deployment.

data/public/docs/guides/agentic_agents.md

@@ -0,0 +1,137 @@
+# Agentic Agents (ReAct loop)
+
+By default a Legate LLM agent **plans once, then executes**: the planner asks the
+model for a complete list of tool steps up front, and the agent runs them in
+order. That is fast and predictable, but it can't react — if step 2 returns
+something unexpected, step 3 still runs the original plan.
+
+The **agentic** strategy replaces the single up-front plan with an
+observe → think → act loop (the "ReAct" pattern): the agent takes **one** action,
+observes the result, then decides the next action with that result in hand. It
+keeps going until the model produces a final answer.
+
+## When to use it
+
+| Use **`:plan`** (default) when… | Use **`:react`** when… |
+|---|---|
+| The steps are known ahead of time | Later steps depend on earlier results |
+| You want the fewest LLM round-trips | The task is exploratory or multi-step |
+| The task is a single tool call | A tool may fail and the agent should adapt |
+
+`:react` makes more LLM calls (one per step) in exchange for the ability to
+course-correct. For a one-shot tool call, `:plan` is cheaper and just as good.
+
+## Enabling it
+
+### In the DSL
+
+```ruby
+definition = Legate::AgentDefinition.new
+definition.define do |a|
+  a.name :researcher
+  a.description 'Looks things up step by step.'
+  a.instruction 'Answer the user by searching and reading, one step at a time.'
+  a.use_tool :search
+  a.use_tool :fetch
+  a.planning_strategy :react   # opt in; omit (or :plan) for the default
+end
+```
+
+`planning_strategy` accepts `:plan` (default) or `:react`. It applies to `:llm`
+agents; it has no effect on workflow agents (`:sequential`, `:parallel`, `:loop`).
+
+### In the web UI
+
+On an agent's detail page, open **Edit Type**. Alongside *Agent Type* there is a
+**Planning Strategy** dropdown — choose *ReAct (agentic loop)* and save. The same
+control is available when creating a new agent. The agent's type panel shows a
+**ReAct** tag when the loop is active.
+
+## How the loop works
+
+Each turn, the planner sends the model the user's request plus every observation
+so far, and asks for the single next action as a JSON object:
+
+```jsonc
+// call a tool
+{"thought": "I should search first", "action": "tool",
+ "tool_name": "search", "tool_input": {"q": "ruby agents"}}
+
+// finish
+{"thought": "I have enough to answer", "action": "final",
+ "answer": "Here's what I found…"}
+```
+
+1. **Think** — `Planner#reason_next_action` asks the adapter for the next action
+   and turns the answer into a `Legate::Agentic::Decision`. How it asks depends on
+   the provider (see [Native function calling](#native-function-calling) below):
+   either a native tool call or the JSON object above parsed out of the response.
+2. **Act** — if the decision is a tool call, the agent runs it through the same
+   executor, event logging, and state-delta machinery as the default strategy.
+   Tool requests and results are appended to the session exactly as usual.
+3. **Observe** — the (sanitized) result is appended to the running list of
+   observations and fed back into the next turn's prompt.
+
+The loop ends when the model returns `"action": "final"`; the answer becomes the
+agent's result event, identical in shape to a `:plan` run.
+
+### Tool errors don't abort the loop
+
+If a tool returns an error — or raises — the failure is captured as an
+**observation** rather than ending the turn. The model sees the error on the next
+step and can retry with different input, try another tool, or give up gracefully.
+This is the headline advantage over plan-then-execute, which stops at the first
+failed step.
+
+### Safeguards
+
+- **Iteration cap.** The loop runs at most `DEFAULT_MAX_ITERATIONS` (8) steps, so
+  a confused agent can't loop forever. If it hasn't finished by then it makes one
+  best-effort pass — asking the model to answer from the observations gathered —
+  and returns that as the result. If even that can't be produced (e.g. no LLM
+  available), it returns an error result noting the cap.
+- **Loop-breaker.** If the model repeats the *exact same* action and gets the
+  *exact same* result, re-running won't help — the loop stops early (again with a
+  best-effort summary) instead of spinning through the rest of the budget.
+- **Observation truncation.** Tool outputs are trimmed before being fed back so a
+  big result doesn't blow up the next turn's prompt: deeply-nested structures
+  become `[Complex Result Structure]`, and long strings are cut to ~2,000
+  characters with a `[truncated N chars]` marker. Simple scalar results pass
+  through intact.
+- **Tool-name validation.** A tool name from the model is validated against the
+  agent's registry (and its delegation targets) before it is interned or run —
+  the same guard the multi-step planner uses — so untrusted model output can't
+  invoke arbitrary tools.
+
+## Native function calling
+
+How the loop *asks* for the next action depends on the LLM adapter:
+
+- **Adapters with native function calling** (Gemini, the default) receive the
+  tools as structured function declarations and return a real function call. No
+  JSON is parsed out of prose — the tool name and arguments come back typed,
+  which is markedly more reliable. This happens automatically; you don't
+  configure anything.
+- **Adapters without it** (Ollama, custom adapters) fall back to the JSON-object
+  prompt shown above. Same `Decision`, same loop — only the mechanism differs.
+
+An adapter advertises support via `supports_function_calling?` and implements
+`generate_with_tools(prompt, tools:)` (see
+[LLM Providers](llm_providers)). The validation, safeguards, and everything
+downstream are identical on both paths; the agent's registered tools and its
+delegation targets are offered either way.
+
+> Scope: native function calling powers the **agentic** next-action decision. The
+> default plan-then-execute planner still uses JSON-mode output.
+
+## What stays the same
+
+Switching strategies does **not** change anything else about your agent. Tools,
+sessions, state deltas, callbacks (`before_tool`, `after_tool`, `before_model`,
+…), MCP integration, and the final result-event shape all behave identically.
+`:react` is purely a change in *how the next action is chosen*.
+
+## Related
+
+- [LLM Providers](llm_providers) — the adapter the loop reasons through.
+- [Legate Planner](../core_concepts/legate_planner) — the default plan-then-execute flow.