scout-ai 1.2.3 → 2.0.0

data/doc/user/Python.md

@@ -0,0 +1,159 @@
+# Python Tasks for Agents
+
+This page explains how to write agent tools in Python. It is intended for
+workflow authors who want to use Python libraries for specific tasks while
+keeping agent orchestration in Scout-AI.
+
+**You should read this if:** you have Python code or libraries you want to
+expose as agent tools.
+
+---
+
+## The idea
+
+A Scout-AI agent is a directory. If that directory contains a `python/`
+subdirectory with `.py` files, Scout-AI automatically loads those files as
+workflow tasks — exactly like Ruby workflow tasks.
+
+This lets you:
+- Keep **agent orchestration** in Scout-AI and Ruby.
+- Write **task logic** in Python with full access to Python libraries.
+
+---
+
+## Agent directory layout
+
+```text
+MyAgent/
+├── start_chat            # system prompt
+└── python/
+    ├── search.py         # Python tasks
+    └── summarize.py
+```
+
+No `workflow.rb` file is needed if Python tasks are sufficient.
+
+---
+
+## Writing a Python task
+
+Create a Python function with type hints and register it with `scout.task()`:
+
+```python
+# python/greet.py
+import scout
+
+def greet(name: str, excited: bool = False) -> str:
+    """
+    Generate a greeting.
+
+    Args:
+        name: Name of the person to greet.
+        excited: Whether to add an exclamation mark.
+
+    Returns:
+        Greeting text.
+    """
+    return f"Hello, {name}{'!' if excited else ''}"
+
+scout.task(greet)
+```
+
+Each `.py` file directly under `python/` is auto-loaded. A single file can
+register multiple functions.
+
+---
+
+## Using the agent
+
+Once the directory is set up, load the agent normally:
+
+```ruby
+require 'scout-ai'
+
+agent = LLM::Agent.load_agent('MyAgent', endpoint: :openai)
+agent.start
+agent.user 'Greet Alice using your tool'
+puts agent.chat
+```
+
+The Python tasks are available as tools through the workflow auto-export
+mechanism. The model can call them just like any other tool.
+
+From the CLI:
+
+```bash
+scout-ai agent ask MyAgent "Greet Alice"
+```
+
+---
+
+## Guidelines for good Python tasks
+
+A good Python task is a clean, standalone function:
+
+- Use **explicit type hints** — they become the tool's parameter schema.
+- Use **sensible defaults** for optional parameters.
+- Write a **docstring** with an `Args:` section — it becomes the tool
+  description.
+- Return **plain strings, lists, or JSON-serializable objects**.
+- Keep **side effects explicit and minimal**.
+
+Example:
+
+```python
+import scout
+
+def top_words(text: str, limit: int = 10) -> list[str]:
+    """
+    Return the most frequent words in a text.
+
+    Args:
+        text: Input text to analyze.
+        limit: Maximum number of words to return.
+
+    Returns:
+        A list of the most frequent words.
+    """
+    counts = {}
+    for word in text.lower().split():
+        counts[word] = counts.get(word, 0) + 1
+    return [w for w, _ in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:limit]]
+
+scout.task(top_words)
+```
+
+---
+
+## When to use Python tasks
+
+Use Python when:
+- The logic is **easier in Python** (data processing, ML, scientific computing).
+- You need **specific Python libraries** (pandas, numpy, scikit-learn, etc.).
+- The task is a **standalone function** with typed inputs and a structured
+  return.
+
+Keep the **orchestration** (agent loops, delegation, conversation management)
+in Ruby/Scout-AI. Use Python for the **leaf tasks** that benefit from Python
+libraries.
+
+---
+
+## Common mistakes
+
+- **Putting files in subdirectories**: Only `.py` files directly under
+  `python/` are auto-loaded. Don't nest them further.
+- **Forgetting `scout.task()`**: Without registration, the function is not
+  exposed as a tool.
+- **Missing type hints**: The model needs type information to know how to call
+  the tool. Without hints, parameters may not be properly described.
+- **Not using docstrings**: The docstring becomes the tool description shown to
+  the model. Without it, the model doesn't know what the tool does.
+
+---
+
+## Next steps
+
+- [BuildingAgents.md](BuildingAgents.md) — agent lifecycle and Ruby tools.
+- [ToolCalling.md](ToolCalling.md) — how tools are declared and called.
+- [WritingChats.md](WritingChats.md) — the chat file format.

data/doc/user/RunningInference.md

@@ -0,0 +1,200 @@
+# Running Inference
+
+This page explains how to configure inference endpoints, choose models, and
+run conversations from the CLI or Ruby. It is intended for workflow authors who
+need to connect Scout-AI to LLM providers.
+
+**You should read this if:** you want to configure which LLM provider and model
+your agents and chats use.
+
+---
+
+## What an endpoint is
+
+An **endpoint** is a named configuration that bundles a provider, a model, and
+credentials. You configure endpoints once and reference them by name.
+
+Endpoints solve a portability problem: your agent code and chat files stay the
+same regardless of whether you're using OpenAI, Anthropic, or a local model.
+
+---
+
+## Configuring endpoints
+
+Endpoints are stored in Scout config. The simplest way is the CLI:
+
+```bash
+# OpenAI (uses OPENAI_API_KEY env var)
+scout-ai config set openai model=gpt-4o
+
+# Anthropic
+scout-ai config set anthropic provider=anthropic model=claude-sonnet-4-20250514
+
+# Local model via Ollama
+scout-ai config set local ollama model=qwen2.5:14b url=http://localhost:11434/v1
+```
+
+You can also edit the config file directly. Endpoint configs live under their
+own section:
+
+```ini
+[openai]
+model = gpt-4o
+
+[anthropic]
+provider = anthropic
+model = claude-sonnet-4-20250514
+
+[local]
+provider = ollama
+model = qwen2.5:14b
+url = http://localhost:11434/v1
+```
+
+---
+
+## Using endpoints
+
+### From the CLI
+
+```bash
+# Use the default endpoint
+scout-ai llm ask "Hello"
+
+# Use a specific endpoint
+scout-ai llm ask -e anthropic "Hello"
+
+# Use a specific model on an endpoint
+scout-ai llm ask -e openai -m gpt-4o-mini "Hello"
+```
+
+### From Ruby
+
+```ruby
+# Reference an endpoint by name
+agent = LLM.agent(endpoint: :anthropic)
+
+# Or set inline
+agent = LLM.agent
+agent.option :endpoint, :anthropic
+agent.option :model, 'claude-sonnet-4-20250514'
+```
+
+### In chat files
+
+```text
+endpoint: anthropic
+model: claude-sonnet-4-20250514
+```
+
+These are sticky options — they persist across the conversation.
+
+---
+
+## Supported providers
+
+Scout-AI supports several providers out of the box:
+
+| Provider | Key | Notes |
+|----------|-----|-------|
+| OpenAI | `openai` | GPT models, uses `OPENAI_API_KEY` |
+| Anthropic | `anthropic` | Claude models, uses `ANTHROPIC_API_KEY` |
+| Ollama | `ollama` | Local models via Ollama API |
+| OpenAI-compatible | (custom) | Any server exposing the OpenAI API format (vLLM, etc.) |
+
+### Setting API keys
+
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+For local models (Ollama, vLLM), no API key is typically needed.
+
+---
+
+## Caching
+
+By default, Scout-AI caches inference results. This means:
+
+- Asking the same question twice returns the cached answer instantly.
+- Workflow jobs that produce the same chat are not re-run.
+- You can reproduce results deterministically.
+
+To disable caching for a specific call:
+
+```ruby
+agent.option :persist, false
+```
+
+---
+
+## Choosing the right model
+
+| Use case | Suggested approach |
+|----------|-------------------|
+| Fast, cheap interactions | GPT-4o-mini, Claude Haiku, or a small local model |
+| Complex reasoning | GPT-4o, Claude Sonnet/Opus |
+| Code generation | GPT-4o, Claude Sonnet |
+| Local / offline | Ollama with Qwen2.5 or Llama 3.1 |
+
+The model is configured per-endpoint but can be overridden per-call:
+
+```bash
+scout-ai llm ask -e openai -m gpt-4o-mini "Quick question"
+```
+
+---
+
+## The inference flow
+
+When you call `agent.chat` or `scout-ai llm ask`, Scout-AI:
+
+1. Collects the messages (from the chat file or agent state).
+2. Applies any context management (see [ManagingContext.md](ManagingContext.md)).
+3. Formats the messages for the provider's API.
+4. Sends to the endpoint.
+5. If the model calls a tool, executes it and re-sends (automatic).
+6. Returns the final text response.
+
+This is all automatic. You configure the endpoint and model; Scout-AI handles
+the rest.
+
+Persistence, however, differs slighly between the two CLIs:
+
+- `scout-ai agent ask ... -c <chat>` sets the agent's `save_file` to
+  `<chat>.files/<name>.chat` (`agent.chat` by default; a named agent writes
+  `worker.chat`), runs the agent through `agent.chat` (so the
+  auto-save hook fires), and also appends the new messages to `<chat>`
+  itself — a dual write. The `agent.chat` should contain also the agent
+  instructions. Delegated society conversations, when they exist, are written
+  under `<chat>.files/<name>.society/<agent>/<conversation>/agent.chat`
+  (older versions used `<chat>.files/log/agent.chat` and
+  `<chat>.files/log/society/…`; those files are still read by provenance but
+  never written or migrated).
+- `scout-ai llm ask ... -c <chat>` accepts an `agent_save_file:` option
+  internally, but `LLM.ask` currently extracts that option and drops it
+  without applying it, unless an agent is defined inside the chat, in which
+  case that agent will get configured with the `save_file`.
+
+---
+
+## Common mistakes
+
+- **Forgetting to set the API key**: The most common error. Make sure the
+  environment variable matches your provider.
+- **Using the wrong endpoint name**: Endpoint names are case-sensitive and must
+  match your config.
+- **Expecting streaming by default**: Streaming is available but not enabled
+  by default. Check the CLI flags or Ruby options.
+- **Not realizing caching is on**: If you're not seeing new responses to the
+  same question, it may be cached. Use `persist: false` to bypass.
+
+---
+
+## Next steps
+
+- [ManagingContext.md](ManagingContext.md) — what happens when conversations
+  get long.
+- [BuildingAgents.md](BuildingAgents.md) — agents with persistent endpoints.
+- [ToolCalling.md](ToolCalling.md) — tools during inference.

data/doc/user/ToolCalling.md

@@ -0,0 +1,193 @@
+# Tool Calling
+
+This page explains how to give Scout-AI agents and chats access to callable
+tools. It is intended for workflow authors who want the LLM to query data,
+run code, or interact with external systems during inference.
+
+**You should read this if:** you want the model to do more than generate text.
+
+---
+
+## What tools are
+
+Tools are functions the LLM can call during inference. When a tool is
+available, the model sees its name, description, and parameter schema. If the
+model decides to call the tool, Scout-AI executes it, appends the result to the
+conversation, and re-sends the conversation so the model can use the result.
+
+Scout-AI supports three kinds of tools:
+
+| Kind | How to declare | What it provides |
+|------|---------------|-----------------|
+| **Workflow tools** | `tool:` / `introduce:` in chat, or auto-wired from agent workflow | Typed tasks from a Scout Workflow |
+| **Knowledge base tools** | `kb:` in chat | Database lookups |
+| **MCP tools** | `mcp:` in chat | Any MCP-compatible external server |
+
+---
+
+## Workflow tools
+
+A Scout Workflow is a module of tasks with typed inputs and outputs. When you
+expose a workflow as tools, each task becomes a callable function.
+
+### Exposing an entire workflow
+
+```text
+introduce: MyWorkflow
+```
+
+This auto-generates a tool definition for every task in the workflow. The model
+can call any task, providing inputs as arguments.
+
+### Exposing a specific task
+
+```text
+tool: MyWorkflow my_task input1=value1 input2=value2
+```
+
+This exposes only `my_task` from `MyWorkflow`, with some inputs pre-filled.
+
+### How it works
+
+When the model calls a workflow tool:
+
+1. Scout-AI runs the task as a workflow job.
+2. The job goes through Scout's dependency resolution and caching.
+3. The result is converted to text and returned as a tool output message.
+4. The model sees the result and continues.
+
+### Inline workflow definition
+
+In Ruby, you can define a workflow inline on an agent:
+
+```ruby
+agent.workflow do
+  task :search => :string do |query|
+    # your search logic here
+    "Results for: #{query}"
+  end
+
+  task :save => :string do |path, content|
+    File.write(path, content)
+    "Saved to #{path}"
+  end
+end
+```
+
+The model can now call `search` and `save` as tools.
+
+---
+
+## Knowledge base tools
+
+If your agent or chat has a knowledge base, its databases become tools the
+model can query.
+
+```text
+kb: my_database [genes proteins interactions]
+```
+
+This exposes two tools per database:
+- `my_database(entities: [...])` — find related entities.
+- `my_database_association_details(entities: [...])` — get association details.
+
+### From an agent
+
+```ruby
+agent = LLM::Agent.new(knowledge_base: 'my_kb')
+```
+
+The KB's databases are automatically wired as tools.
+
+---
+
+## MCP tools
+
+The Model Context Protocol (MCP) is an open standard for exposing tools to
+LLMs. Scout-AI can connect to any MCP server.
+
+### HTTP MCP server
+
+```text
+mcp: https://api.example.com/mcp/
+```
+
+### Stdio MCP server
+
+```text
+mcp: stdio my-mcp-command arg1 arg2
+```
+
+### Selecting specific tools
+
+```text
+mcp: https://api.example.com/mcp/ [search write_file]
+```
+
+Only the named tools will be available.
+
+---
+
+## Tool calling in action
+
+When a tool is called, the conversation grows with two messages:
+
+```text
+function_call: {"name":"search","arguments":{"query":"ruby blocks"},"id":"call_1"}
+function_call_output: {"id":"call_1","content":"Ruby blocks are..."}
+```
+
+The tool-calling loop is automatic. If the model calls multiple tools in one
+turn, or calls a tool and then needs to call another, Scout-AI handles the
+iteration until the model responds with plain text.
+
+---
+
+## Controlling tool behavior
+
+### Forcing a tool call
+
+```ruby
+agent.option :tool_choice, {type: 'function', function: {name: 'search'}}
+```
+
+### Clearing tools
+
+```text
+clear_tools: true
+```
+
+---
+
+## When to use tools vs. direct code
+
+Tools are for things the **model** should decide to do. If you know you need a
+piece of data before inference, just put it in the chat as a file or user
+message. Use tools when:
+
+- The model needs to **decide** whether to look something up.
+- The model needs to **iterate** — call a tool, see results, call another.
+- The operation is **expensive** and should only run when needed.
+- You want the **provenance** of tool calls recorded in the chat history.
+
+---
+
+## Common mistakes
+
+- **Declaring tools but forgetting the workflow**: If you write
+  `introduce: MyWorkflow` but the workflow is not on the agent's load path,
+  the tools won't resolve.
+- **Expecting tool results to be structured**: Tool results are always
+  converted to text before being shown to the model. If you need structured
+  data, use JSON format and tell the model to expect it.
+- **Overloading the model with too many tools**: Each tool adds to the context
+  size. Introduce only the workflows relevant to the task.
+
+---
+
+## Next steps
+
+- [BuildingAgents.md](BuildingAgents.md) — how agents auto-wire tools.
+- [RunningInference.md](RunningInference.md) — endpoint and model configuration.
+- [ManagingContext.md](ManagingContext.md) — what happens when tool calls
+  accumulate and the context gets long.