scout-ai 1.2.5 → 2.0.0

data/doc/LLM.md

@@ -1,356 +0,0 @@
-# LLM
-
-This package provides a compact layer to talk to multiple LLM backends while keeping:
-
-- **configuration reproducible** (named endpoints)
-- **prompts reproducible** (chat files)
-- **tool calling first-class** (Workflow tasks, KnowledgeBase databases, MCP tools)
-
-The core entry points are:
-
-- `LLM.ask(question, options={}, &block)` — ask a model (optionally with tools)
-- `LLM.chat(...)` — compile/expand a chat file or message array into final messages
-- `LLM.options(messages)` — extract per-chat options (`endpoint`, `model`, `format`, …)
-- `LLM.print(messages)` — serialize messages back to chat-file format
-- `LLM.embed(text, options={})` — embeddings (not the focus of this document)
-
-If you are new to Scout-AI, start with `USER_GUIDE.md`.
-
-For stateful multi-turn conversations, see `doc/Agent.md`.
-
-For the full chat-file role reference, see `doc/Chat.md`.
-
----
-
-## 0. Getting started path
-
-A good first learning sequence is:
-
-1. create one endpoint under `~/.scout/etc/AI/<name>`
-2. run `scout-ai llm ask -e <name> "Say hi"`
-3. create a chat file and continue it with `-c`
-4. load a stateful `LLM::Agent`
-5. expose one Scout `Workflow` as a tool
-
-Use `USER_GUIDE.md` for the step-by-step walkthrough, then come back here for backend and CLI details.
-
----
-
-## 1. Endpoints: configuring inference points (`~/.scout/etc/AI/<endpoint>`)
-
-Scout-AI uses **named endpoints** so colleagues can agree on short names like `nano` or `deep`.
-
-At runtime, `LLM.ask(..., endpoint: :nano)` will load:
-
-```text
-~/.scout/etc/AI/nano
-```
-
-This file is YAML.
-
-Minimum useful keys:
-
-- `backend`: which backend to use (`responses`, `openai`, `anthropic`, `ollama`, `vllm`, `openwebui`, `bedrock`, `relay`)
-- `url`: server URL (only for backends that need one, e.g. `ollama`, `openwebui`)
-- `model`: backend-specific model id
-
-Any **additional keys are passed to the backend** and may be interpreted there.
-
-Examples:
-
-`~/.scout/etc/AI/nano`
-
-```yaml
-backend: responses
-model: gpt-5-nano
-```
-
-`~/.scout/etc/AI/deep`
-
-```yaml
-backend: responses
-model: gpt-5
-reasoning_effort: high
-text_verbosity: high
-```
-
-`~/.scout/etc/AI/ollama`
-
-```yaml
-backend: ollama
-url: http://localhost:11434
-model: llama3.1
-```
-
-How they are used:
-
-```ruby
-LLM.ask "Say hi", endpoint: :nano
-LLM.ask "Think harder", endpoint: :deep
-```
-
-From the CLI:
-
-```bash
-scout-ai llm ask -e nano "Say hi"
-```
-
----
-
-## 2. `LLM.ask`: the core call
-
-### 2.1 Input types
-
-The `question` argument can be:
-
-- a String (free text)
-- a **path to a chat file** (if the string looks like a filename and exists)
-- an Array of `{role:, content:}` hashes
-- a `Chat` (which is an annotated array)
-
-Internally `LLM.ask` always compiles input via `LLM.chat` first.
-
-### 2.2 Option resolution order
-
-Options come from multiple places:
-
-1) options extracted from the compiled messages (`LLM.options(messages)`)
-2) options passed explicitly to `LLM.ask(question, options)`
-3) endpoint YAML (`~/.scout/etc/AI/<endpoint>`) is merged in (as defaults)
-
-### 2.3 Caching (`persist`)
-
-`LLM.ask` caches responses by default via `Persist.persist`.
-
-- default: `persist: true`
-- set `persist: false` to disable caching
-
-The cache key includes the endpoint name, messages, and most options.
-
-### 2.4 Return value
-
-- default: returns the assistant content string
-- if `return_messages: true`: returns the full message trace (including tool calls)
-
----
-
-## 3. Chat compilation (`LLM.chat`) and why it matters
-
-`LLM.chat` is what makes chat files powerful.
-
-It expands special roles **before** calling the backend:
-
-- imports: `import`, `continue`, `last`
-- pruning: `clear`, `skip`
-- workflow execution: `task`, `inline_task`, `exec_task`, and then `job`, `inline_job`
-- file inclusion: `file`, `directory`, `image`, `pdf`
-
-See `doc/Chat.md` for exact behavior and role syntax.
-
----
-
-## 4. Backends (and what is “passed through”)
-
-Backends are selected by `backend:` (from endpoint YAML, env/config, or explicit options).
-
-Currently supported backends (see `lib/scout/llm/backends/`):
-
-- `responses` — OpenAI Responses API style (default). Supports:
-  - JSON Schema responses (`format:` as schema)
-  - multimodal (`image:`, `pdf:` roles)
-  - session continuation (`previous_response_id`)
-  - optional web search tool (`websearch`)
-- `openai` — OpenAI Chat Completions style
-- `anthropic` — Anthropic Messages API style
-- `ollama` — local Ollama server
-- `vllm` — vLLM OpenAI-compatible server
-- `openwebui` — OpenWebUI-compatible chat/completions
-- `bedrock` — AWS Bedrock runtime
-- `relay` — simple SCP/poll relay
-
-### 4.1 Common backend options
-
-Many backends accept the same high-level keys:
-
-- `model`, `url`, `key`
-- `request_timeout`
-- `log_errors`
-- `tools`
-
-And then backend-specific keys are forwarded (for example: reasoning/text options for `responses`).
-
-### 4.2 Responses session continuation (`previous_response_id`)
-
-If you use the Responses backend and provide a `previous_response_id`, Scout-AI will:
-
-- keep only the messages after the most recent `previous_response_id` marker (so you do not resend the entire conversation)
-- pass `previous_response_id` to the backend
-
-If you set `previous_response: false`, session continuation is disabled.
-
----
-
-## 5. Tools and function calling
-
-Scout-AI represents tools as a **hash**:
-
-```ruby
-tools = {
-  "tool_name" => [handler, tool_definition]
-}
-```
-
-Where:
-
-- `handler` can be:
-  - a `Workflow`
-  - a `KnowledgeBase`
-  - a `Proc` (custom tool implementation)
-- `tool_definition` is an OpenAI-style function schema (adapted per backend)
-
-### 5.1 Providing tools
-
-You can provide tools in three main ways:
-
-1) programmatically: `LLM.ask(..., tools: {...})`
-2) via chat roles: `tool:`, `kb:`, `association:`, `mcp:`
-3) via an Agent: `LLM::Agent` automatically exports a workflow/KB as tools
-
-### 5.2 Workflow tools
-
-```ruby
-workflow_tools = LLM.workflow_tools(Baking)
-LLM.ask "Bake muffins", tools: workflow_tools
-```
-
-Or in a chat file:
-
-```text
-tool: Baking bake_muffin_tray
-```
-
-### 5.3 KnowledgeBase tools
-
-```ruby
-kb_tools = LLM.knowledge_base_tool_definition(kb)
-LLM.ask "Query relationships", tools: kb_tools
-```
-
-Or in a chat file:
-
-```text
-association: brothers test/data/person/brothers undirected=true
-```
-
-### 5.4 Tool execution and output limits
-
-Tool calls are executed by `LLM.process_calls`.
-
-To protect the context window, tool outputs are capped (config key `:max_content_length` under `:llm_tools`).
-
-If a tool returns more than the max length, the content is replaced by an exception-like JSON string.
-
----
-
-## 6. Convenience helpers
-
-### 6.1 `LLM.workflow_ask`
-
-```ruby
-LLM.workflow_ask(Baking, "Bake muffins", endpoint: :nano)
-```
-
-### 6.2 `LLM.knowledge_base_ask`
-
-```ruby
-LLM.knowledge_base_ask(kb, "Who is X's brother in law?", endpoint: :nano)
-```
-
----
-
-## 7. CLI usage
-
-### 7.1 `scout-ai llm ask`
-
-The main “stateless” CLI.
-
-```bash
-scout-ai llm ask -e nano "Say hi"
-```
-
-For convenience prompt does not need quotes.
-
-```bash
-scout-ai llm ask -e nano Say hi
-```
-
-Useful flags:
-
-- `-e/--endpoint <name>`
-- `-m/--model <model_id>`
-- `-b/--backend <backend>`
-- `-c/--chat <file>` — read/append to a chat file
-- `-i/--imports <a,b,c>` — import other chat files
-- `-t/--template <name_or_path>` — templates with optional `???` placeholder
-- `-f/--file <path>` — inline a file into the prompt
-- `-d/--dry_run` — print the compiled conversation (no model call)
-
-The configuration files under etc/config can be used to setup default
-endpoints or models.
-
-```config
-# ~/.scout/etc/config
-endpoint nano ask
-```
-
-### 7.2 `scout-ai agent ask`
-
-The “agent-aware” CLI.
-
-```bash
-scout-ai agent ask Baking Bake a tray of muffins
-```
-
-It loads the agent (workflow + knowledge base + start_chat) and runs a stateful conversation.
-
-See `doc/Agent.md`.
-
----
-
-## 8. Programmatic use (control loops)
-
-For loops, branching, delegation, and structured iteration, use `LLM::Agent`.
-
-See `doc/Agent.md` for the full API and examples.
-
----
-
-## 9. Minimal end-to-end example
-
-1) Create an endpoint file:
-
-```yaml
-# ~/.scout/etc/AI/nano
-backend: responses
-model: gpt-5-nano
-```
-
-2) Ask from the CLI:
-
-```bash
-scout-ai llm ask -e nano Say hi
-```
-
-3) Use a chat file with a workflow tool:
-
-```text
-user:
-
-tool: Baking bake_muffin_tray
-
-Bake muffins using the tool.
-```
-
-```bash
-scout-ai llm ask -c baking.chat -e nano
-```

data/doc/PythonAgentTasks.md

@@ -1,333 +0,0 @@
-# Python-backed Agent Tasks
-
-This guide explains how to write Scout-AI agent tasks in Python.
-
-This document is about writing Python-backed workflow tasks for Ruby-side agents. If you want to use Scout-AI chats and agents from Python, see `../python/README.md`.
-
-The key idea is simple:
-
-- a normal Scout agent can be packaged as a directory
-- if that directory contains a `python/` subdirectory with `*.py` files, `LLM::Agent.load_agent` can auto-load those files as workflow tasks
-- the resulting tasks are exposed to the agent exactly like regular workflow tasks
-
-This gives you a convenient way to keep:
-
-- chat and agent orchestration in Scout-AI and Ruby
-- task logic in Python
-
-For the underlying generic mechanism, see `~/git/scout-rig/doc/PythonWorkflow.md`.
-
-## 1. When to use Python-backed tasks
-
-Use Python-backed agent tasks when:
-
-- the logic is easier to write in Python
-- you want access to Python libraries directly
-- the task is naturally a standalone function with typed inputs and a structured return value
-- you still want Scout workflow behavior such as persistence, job directories, provenance, and CLI integration
-
-Do not use this mechanism just to avoid Ruby entirely. The most effective pattern is usually:
-
-- use Ruby and Scout workflows to orchestrate the overall control loop
-- use Python for the tasks that benefit from Python libraries or Python-first implementations
-
-## 2. How agent auto-loading works
-
-`LLM::Agent.load_agent` resolves an agent in this order:
-
-- named workflow
-- agent directory with `workflow.rb`
-- agent directory with `knowledge_base/`
-- agent directory with `start_chat`
-- agent directory with `python/*.py`
-
-The important part for Python-backed agents is in `lib/scout/llm/agent.rb`:
-
-- if the agent directory has a `python/` subdirectory
-- and that directory contains `*.py` files
-- Scout requires `scout/workflow/python`
-- then calls `PythonWorkflow.load_directory(agent_path.python, 'ScoutAgent')`
-
-This means that for agent directories the convention is slightly different from the generic `PythonWorkflow` case:
-
-- generic workflow usage often uses `python/task/<name>.py`
-- agent auto-loading uses all `*.py` files directly under `python/`
-
-So for an agent directory, place task files directly in `python/`.
-
-Two practical notes:
-
-- every `*.py` file directly under `python/` is considered during auto-loading
-- each file may register one or more functions with `scout.task(...)`
-
-## 3. Minimal agent directory layout
-
-A minimal Python-backed agent directory can look like this:
-
-```text
-MyAgent/
-├── start_chat
-└── python/
-    ├── hello.py
-    └── summarize.py
-```
-
-Optional additions:
-
-```text
-MyAgent/
-├── start_chat
-├── knowledge_base/
-└── python/
-    ├── hello.py
-    └── summarize.py
-```
-
-You do not need a `workflow.rb` file if the Python tasks are enough.
-
-## 4. Minimal Python task example
-
-Create `python/hello.py`:
-
-```python
-import scout
-
-def hello(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(hello)
-```
-
-This file does three things:
-
-- defines a normal Python function
-- uses type hints and defaults
-- registers the function with `scout.task(...)`
-
-That registration is what makes the function visible to `PythonWorkflow`.
-
-A single file can register multiple functions if you want a small family of related tasks in one place.
-
-## 5. Minimal `start_chat`
-
-A matching `start_chat` can be very small:
-
-```text
-system:
-
-You are a helpful assistant with a few Python-backed tools.
-Use them when helpful.
-```
-
-If the agent is loaded with `LLM::Agent.load_agent("MyAgent")`, the Python tasks are loaded as workflow tasks, and the agent can expose them automatically just as it would for any other workflow-backed agent.
-
-## 6. Loading the agent
-
-Ruby:
-
-```ruby
-require 'scout-ai'
-
-agent = LLM::Agent.load_agent('MyAgent', endpoint: :nano)
-agent.start
-agent.user 'Greet Alice using your tool'
-puts agent.chat
-```
-
-If the backend supports function calling, the Python-backed tasks are available as tools through the workflow auto-export mechanism.
-
-## 7. Writing good Python tasks
-
-A Python-backed task should behave like a clean, standalone function.
-
-Recommended rules:
-
-- use explicit type hints
-- use defaults where possible
-- write a short docstring preamble
-- document arguments in Google-style `Args:` sections
-- return plain strings, arrays, or JSON-serializable objects
-- keep side effects explicit and minimal
-
-A better 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)
-```
-
-## 8. Type mapping
-
-The Python function signature is converted into Scout workflow inputs and return types through the metadata produced by `scout.task(...)`.
-
-Important mappings include:
-
-- `str` -> `:string`
-- `int` -> `:integer`
-- `float` -> `:float`
-- `bool` -> `:boolean`
-- `list[str]` -> `:array`
-- `path`-like metadata -> `:file` or `:file_array`
-
-For the full mapping rules, see `~/git/scout-rig/doc/PythonWorkflow.md`.
-
-## 9. Return values
-
-At execution time the Python task prints its result to stdout and Scout interprets it as follows:
-
-- valid JSON -> parsed as JSON
-- array/file-array outputs -> split on newlines if not JSON
-- anything else -> stripped string
-
-In practice, this means:
-
-- simple strings are easy
-- lists are easy
-- dictionaries and richer results should usually be JSON-serializable
-
-If you want structured outputs, return JSON-friendly Python objects.
-
-## 10. Standalone CLI behavior
-
-A Python task file can also be run directly.
-
-Metadata mode:
-
-```bash
-python python/hello.py --scout-metadata
-```
-
-Execution mode:
-
-```bash
-python python/hello.py --name Alice --excited
-```
-
-If a file registers multiple functions, metadata returns multiple task descriptions, and one function can be selected on the CLI by name.
-
-This is useful because it means your task file is:
-
-- inspectable on its own
-- testable on its own
-- usable both from Scout and from the command line
-
-## 11. Agent-facing pattern
-
-A very effective Scout-AI pattern is:
-
-- package Python tasks in `python/`
-- keep the role instructions in `start_chat`
-- let a Ruby workflow orchestrate the larger multi-agent pattern when needed
-
-For example:
-
-- a Python task does extraction or scoring
-- a Worker agent calls it as a tool
-- a Critic agent checks the result
-- a Session-like workflow coordinates the whole run and writes artifacts with `Step#file`
-
-This keeps the system clean:
-
-- Python does task logic
-- Scout workflows do orchestration
-- chat files do policy and agent behavior
-
-## 12. Relationship to workflows and skills
-
-A Python-backed agent task is still a workflow task.
-
-That matters because it means:
-
-- it participates in the normal Scout workflow/tool machinery
-- it can be exposed as a tool through `LLM::Agent`
-- it fits naturally into workflow-backed `ask` patterns
-
-If you come from systems that talk about “skills”, the Scout-AI equivalent here is:
-
-- `python/*.py` gives you executable task logic
-- `start_chat` gives you the instructional layer
-- the agent directory bundles them together as a reusable toolkit
-
-## 13. A slightly larger example
-
-Directory:
-
-```text
-TextAgent/
-├── start_chat
-└── python/
-    ├── top_words.py
-    └── count_chars.py
-```
-
-`python/count_chars.py`:
-
-```python
-import scout
-
-def count_chars(text: str) -> int:
-    """
-    Count characters in a string.
-
-    Args:
-        text: Input text.
-
-    Returns:
-        Character count.
-    """
-    return len(text)
-
-scout.task(count_chars)
-```
-
-Then in Ruby:
-
-```ruby
-agent = LLM::Agent.load_agent('TextAgent', endpoint: :nano)
-agent.start
-agent.user 'Use your tools to count characters in hello world and list the top words'
-puts agent.chat
-```
-
-## 14. What to read next
-
-For a practical introduction to chats and agents, read:
-
-- `doc/USER_GUIDE.md`
-- `doc/Agent.md`
-- `doc/Chat.md`
-
-For the generic Python workflow mechanism, read:
-
-- `~/git/scout-rig/doc/PythonWorkflow.md`
-
-For the underlying Scout workflow model, read:
-
-- `~/git/scout-gear/doc/Workflow.md`