scout-ai 1.2.3 → 2.0.0

data/doc/user/GettingStarted.md

@@ -0,0 +1,159 @@
+# Getting Started with Scout-AI
+
+This guide helps you install Scout-AI, configure your first inference endpoint,
+and run your first conversation. It is intended for anyone new to the
+framework — both human developers and coding agents.
+
+**You should read this if:** you have never used Scout-AI before.
+
+---
+
+## What is Scout-AI?
+
+Scout-AI is a framework for building AI applications on top of LLMs. It gives
+you:
+
+- **Chats**: plain-text conversation files you can inspect, edit, and version.
+- **Agents**: reusable, stateful assistants with tools and personas.
+- **Tools**: let the model call functions, query databases, or run code.
+- **Multi-agent workflows**: orchestrate specialists to solve complex tasks.
+
+Scout-AI is written in Ruby and uses the Scout Workflow engine for
+reproducibility and provenance.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Ruby 3.0+
+- An LLM provider account (OpenAI, Anthropic, etc.) or a local model
+  (Ollama, vLLM)
+
+### Install Scout-AI
+
+```bash
+gem install scout-ai
+```
+
+Or, if you're working from the source repository:
+
+```bash
+git clone https://github.com/mvazque2/scout-ai.git
+cd scout-ai
+bundle install
+```
+
+### Set your API key
+
+```bash
+# For OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# For Anthropic
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+---
+
+## Configure your first endpoint
+
+An **endpoint** is a named configuration for a provider + model. Configure one
+once and reference it by name.
+
+```bash
+# OpenAI
+scout-ai config set openai model=gpt-4o
+
+# Anthropic
+scout-ai config set anthropic provider=anthropic model=claude-sonnet-4-20250514
+```
+
+---
+
+## Your first conversation
+
+### From the command line
+
+```bash
+scout-ai llm ask "Hello! What can you do?"
+```
+
+You should see a response from the model.
+
+### Using a specific endpoint
+
+```bash
+scout-ai llm ask -e anthropic "Hello!"
+```
+
+---
+
+## Your first chat file
+
+Create a file `hello.chat`:
+
+```text
+system:
+
+You are a friendly assistant. Keep your answers short.
+
+user:
+
+What is 2 + 2?
+```
+
+Run it:
+
+```bash
+scout-ai llm ask -c hello.chat
+```
+
+---
+
+## Your first agent
+
+Agents are **named directories**. Create one:
+
+```bash
+mkdir -p ~/chats/Agent/Greeter
+```
+
+Create `~/chats/Agent/Greeter/start_chat`:
+
+```text
+system:
+
+You are a friendly greeter. Always greet by name.
+```
+
+Use it from the CLI:
+
+```bash
+scout-ai agent ask Greeter "Hi, I'm Alice!"
+```
+
+Or from Ruby:
+
+```ruby
+require 'scout-ai'
+
+agent = LLM.load_agent('Greeter')
+agent.start
+agent.user "Hi, I'm Alice!"
+puts agent.chat
+```
+
+---
+
+## Where to go next
+
+- **[CoreConcepts.md](CoreConcepts.md)** — understand chats, agents, tools, and
+  endpoints.
+- **[WritingChats.md](WritingChats.md)** — master the chat-file format.
+- **[BuildingAgents.md](BuildingAgents.md)** — create agents with tools.
+- **[Cookbook.md](Cookbook.md)** — quick recipes for common tasks.
+
+If you want to understand how Scout-AI is implemented internally, see the
+[../developer/](../developer/) documentation.

data/doc/user/ManagingContext.md

@@ -0,0 +1,163 @@
+# Managing Context
+
+This page explains how Scout-AI handles conversations that grow too long for
+the model's context window, and what you can do to control this behavior. It
+is intended for workflow authors building long-running agents or workflows
+with many tool calls.
+
+**You should read this if:** your agents make many tool calls, use large files,
+or run for many turns.
+
+---
+
+## The problem
+
+LLMs have a limited **context window** — the total number of tokens they can
+process in a single inference call. In agent workflows, the context grows as:
+
+- The conversation accumulates turns.
+- Tool calls add `function_call` and `function_call_output` messages.
+- File imports add large text blocks.
+
+Without management, a long agent session will eventually exceed the context
+window and fail.
+
+---
+
+## How Scout-AI manages context automatically
+
+Scout-AI applies **prompt strategies** — transformations to the conversation
+just before sending it to the model. These are **ephemeral**: they modify only
+what the model sees, never the saved chat file.
+
+The main strategy is **tool-call pruning**. When tool calls accumulate, older
+ones are shortened or removed:
+
+| Threshold | Default | What happens |
+|-----------|---------|-------------|
+| Max tool calls retained | 40 | Older tool call/result pairs beyond this count are removed |
+| Recent tool outputs at full fidelity | 10 | The 10 most recent tool outputs are kept in full |
+| Character budget for tool outputs | 100,000 | Total characters for all retained tool outputs |
+
+This means:
+- The most recent tool calls are always visible in full.
+- Older tool calls are progressively truncated.
+- Very old tool calls are removed entirely.
+
+The model never sees a truncated prompt — it simply gets a shorter conversation
+that fits within its context window.
+
+---
+
+## The `clear` directive
+
+You can explicitly clear conversation history using the `clear:` role in chat
+files:
+
+```text
+clear:
+
+# Everything before this point is removed from the model's view
+```
+
+This is useful when:
+- You want to start a new phase of work without prior context cluttering the
+  prompt.
+- A large file was imported, used, and is no longer needed.
+- You're chaining agents and want each to start fresh.
+
+`clear:` is also ephemeral — it affects what the model sees but does not delete
+the messages from the saved chat file.
+
+---
+
+## Tips for keeping context manageable
+
+### Be selective with file imports
+
+Instead of importing an entire directory, import only the files you need:
+
+```text
+file: src/main.rb
+```
+
+Not:
+
+```text
+directory: src/
+```
+
+### Use tools instead of pre-loading data
+
+If you're not sure whether data will be needed, declare it as a tool instead of
+importing it. The model will fetch it only if needed:
+
+```text
+introduce: DataLookup
+```
+
+Rather than:
+
+```text
+file: huge_dataset.json
+```
+
+### Break long workflows into steps
+
+Instead of one giant conversation, use a Scout workflow to break work into
+steps, each with its own chat:
+
+```ruby
+task :analyze => :string do |input|
+  # Each step gets its own chat, keeping context focused
+end
+```
+
+See [MultiAgentWorkflows.md](MultiAgentWorkflows.md) for patterns.
+
+### Delegate to keep conversations focused
+
+An orchestrator agent can delegate sub-tasks to specialists. Each specialist
+has its own conversation, keeping the orchestrator's context clean:
+
+```ruby
+agent.socialize  # gives the model an 'ask' tool to delegate
+```
+
+See [Delegation.md](Delegation.md) for the delegation API.
+
+---
+
+## What you see vs. what the model sees
+
+It's important to understand that the saved chat file may differ from what the
+model actually saw:
+
+| Aspect | Saved chat file | What the model sees |
+|--------|----------------|-------------------|
+| Tool calls | All of them, in full | Possibly truncated/pruned |
+| File contents | Full file text | Same (unless cleared) |
+| `clear:` directives | Present as markers | Everything before is removed |
+| Conversation history | Complete | Recent turns only (after pruning) |
+
+This is by design: the saved chat is the **ground truth** of what happened;
+the model's prompt is an **optimized view** for the current inference call.
+
+---
+
+## Common mistakes
+
+- **Expecting the saved chat to match the model's input**: They can differ.
+  The saved chat is the record; the model's prompt is ephemeral.
+- **Importing too much data**: Large files eat context. Use tools for
+  on-demand data access.
+- **Not using `clear:` between phases**: If your workflow has distinct phases,
+  clearing between them keeps each phase focused.
+
+---
+
+## Next steps
+
+- [WritingChats.md](WritingChats.md) — the `clear:` directive in context.
+- [ToolCalling.md](ToolCalling.md) — tools as an alternative to pre-loading.
+- [Delegation.md](Delegation.md) — splitting work across agents.

data/doc/user/MultiAgentWorkflows.md

@@ -0,0 +1,256 @@
+# Multi-Agent Workflows
+
+This page explains how to orchestrate multiple agents inside Scout workflows
+for reproducible, pipeline-style AI applications. It is intended for workflow
+authors building complex, multi-step agent systems.
+
+**You should read this if:** you want to build pipelines where agents
+collaborate, pass artifacts, and produce tracked, reproducible results.
+
+---
+
+## The idea
+
+Scout-AI agents are powerful on their own, but for complex applications you
+often need:
+
+- **Multiple steps** — plan, search, execute, review.
+- **Specialized agents** — each with different tools and personas.
+- **Reproducibility** — the same inputs should produce the same results.
+- **Provenance** — you should be able to trace what each agent did.
+
+Scout workflows provide all of this. You define tasks that load and run agents,
+and the workflow engine handles caching, dependencies, and provenance.
+
+---
+
+## The chat_task helper
+
+The core building block is `chat_task` — a Scout workflow task that runs an
+agent:
+
+```ruby
+module MyWorkflow 
+  extend Workflow
+  chat_task :analyze do
+    agent = self.agent('Analyst', chat: chat)
+    agent.start
+    agent.user "Analyze this data."
+    result = agent.chat
+    agent.answer
+  end
+end
+```
+
+The `chat_task` helper and the `agent` method are available in any workflow
+that includes the `AgentWorkflow` mixin.
+
+### What `chat_task` gives you
+
+- **Caching**: The same chat input produces the same output, cached on disk.
+- **Provenance**: Every agent run is recorded with full chat history.
+- **Agent chat sidecar**: the agent's own conversation is always written to
+  `<job>.files/<name>.chat` next to the job (`agent.chat` by default,
+  `worker.chat`/`critic.chat` for named agents), holding the **full** chat
+  (system prompt, tools, every turn), while the job **result** keeps delta
+  semantics — only the messages produced by this run.
+- **Provenance includes the society tree**: `scout-ai llm prov` treats a job
+  and a saved chat the same way here — both are scanned for conversations
+  under `<path>.files/`, namely `<path>.files/*.chat`,
+  `<path>.files/*.society/<agent>/<conversation>/` and the legacy
+  `<path>.files/log/**` (older scouts, still readable). A saved chat skips
+  only its own top-level copy at `<chat>.files/<name>.chat` (and the legacy
+  `<chat>.files/log/agent.chat`); society conversations keep the same
+  `agent.chat` name and are included.
+- **Lazy society tree**: delegated specialist conversations, if any, are
+  saved under `<job>.files/<name>.society/<agent_name>/<conversation>/…`, but
+  only when they exist. Nothing is created eagerly — no job starts with an
+  empty `.files` directory — and parent directories appear on demand.
+- **Dependency tracking**: Tasks can depend on each other.
+
+---
+
+## A simple pipeline
+
+Here's a three-step pipeline: Plan → Execute → Review.
+
+```ruby
+module Pipeline 
+  extend Workflow
+  include AgentWorkflow
+
+  chat_task :plan do |objective|
+    agent = self.agent('Planner', chat: chat)
+    agent.start
+    agent.user objective
+    agent.chat
+  end
+
+  chat_task :execute do |plan|
+    agent = self.agent('Executor', chat: chat)
+    agent.socialize  # executor can delegate to specialists
+    agent.start
+    agent.user "Execute this plan:\n#{plan}"
+    agent.chat
+  end
+
+  chat_task :review do |result|
+    agent = self.agent('Critic', chat: chat)
+    agent.start
+    agent.user "Review this result:\n#{result}"
+    agent.chat
+  end
+end
+```
+
+Each task gets its own agent, its own chat, and its own provenance trail.
+
+---
+
+## Artifact-first collaboration
+
+When agents need to share information, prefer **artifacts** (files on disk)
+over passing everything through the conversation:
+
+```ruby
+chat_task :search do |query|
+  agent = self.agent('Searcher', chat: chat)
+  agent.start
+  agent.user "Research: #{query}"
+  report = agent.chat
+  # Save the report as an artifact
+  Step.write_file('research_report.md', report)
+  report
+end
+
+chat_task :synthesize do |report|
+  # Read the artifact rather than relying on conversation memory
+  full_report = Step.read_file('research_report.md')
+  agent = self.agent('Writer', chat: chat)
+  agent.start
+  agent.user "Write a summary based on this report:\n#{full_report}"
+  agent.chat
+end
+```
+
+Benefits:
+- Each agent's context stays focused on its own task.
+- Artifacts are inspectable and debuggable.
+- Large outputs don't bloat the orchestrator's conversation.
+
+---
+
+## Delegation within workflows
+
+Agents in workflows can also delegate to each other:
+
+```ruby
+chat_task :run do
+  agent = self.agent('Manager', chat: chat)
+  agent.socialize  # model can call ask(agent: 'Worker', prompt: ...)
+  agent.start
+  agent.user "Complete this project."
+  agent.chat
+end
+```
+
+The model decides when to delegate and to whom. Each delegation creates its
+own provenance entry.
+
+See [Delegation.md](Delegation.md) for the full delegation API.
+
+---
+
+## Common patterns
+
+### Linear pipeline
+
+```
+Plan → Execute → Review → Report
+```
+
+Each step depends on the previous one. Simple and predictable.
+
+### Manager-worker
+
+```
+Manager → delegates to → Worker(s)
+         ← returns to ←
+```
+
+The manager agent has `socialize` enabled and dynamically delegates to
+specialists.
+
+### Critic loop
+
+```
+Executor → produces → Critic → reviews → Executor → refines → Critic → ...
+```
+
+Repeat until the critic approves or a max iteration count is reached.
+
+### Branched exploration
+
+```
+           → Agent A →
+Orchestrator → Agent B → Synthesizer
+           → Agent C →
+```
+
+Multiple agents work in parallel on different aspects, then a synthesizer
+combines results.
+
+---
+
+## Logging agent activity
+
+When agents run inside workflow tasks, the agent's own conversation is saved
+to `<job>.files/<name>.chat` (the full chat; `agent.chat` by default,
+`worker.chat` for a `worker` agent), the job result keeps only
+this run's delta, and delegated specialist conversations — when they exist —
+are saved under `<job>.files/<name>.society/<agent_name>/<conversation>/…`.
+Nothing is created up front; directories and files appear only when there is
+something to save.
+
+Chats saved by the CLI get the same sidecar layout: the root conversation is
+copied to `<chat>.files/<name>.chat` and any socialized agents land under
+`<chat>.files/<name>.society/…`. Both jobs and saved chats are examined for
+those conversations, so you can inspect either as provenance:
+
+```bash
+scout-ai llm prov /path/to/job
+scout-ai llm prov /path/to/saved.chat
+```
+
+This shows the full chat history, including any delegations and tool calls.
+Jobs are recognized by their `.info` sidecar; a `.files` directory alone does
+not make a path a job, because saved chats have one too.
+
+Restart snapshots (`.files/resets/<timestamp>.chat`, taken by `agent.start`
+when a prior non-empty chat existed) sit outside `log/` and are recovery
+artifacts, not provenance logs.
+
+See [../developer/Provenance.md](../developer/Provenance.md) for provenance
+internals and [BuildingAgents.md](BuildingAgents.md) for save semantics.
+
+---
+
+## Common mistakes
+
+- **Trying to do everything in one giant chat**: Break work into tasks. Each
+  task gets a fresh context.
+- **Passing everything through conversation**: Use artifacts (files) for large
+  outputs between agents.
+- **Not using `socialize` when the model should decide**: If you want dynamic
+  delegation, enable `socialize` and let the model choose.
+- **Forgetting that tasks are cached**: If you change an agent's `start_chat`
+  but not the task input, you may get a cached result. Clear the cache or
+  change the input.
+
+---
+
+## Next steps
+
+- [Delegation.md](Delegation.md) — the delegation API.
+- [BuildingAgents.md](BuildingAgents.md) — creating agents.
+- [ManagingContext.md](ManagingContext.md) — keeping contexts focused.