scout-ai

Agentic AI and machine‑learning for Scout: a compact layer to train/evaluate models (Ruby, Python/PyTorch, Hugging Face), talk to LLMs across multiple backends, wire Workflow tasks as tools, and build persistent, declarative conversations and agents.

This package sits on top of the Scout stack:

  • scout-essentials — low level functionality (Open, TSV, Persist, Path, ConcurrentStream, Log, etc.)
  • scout-gear — core data modules (TSV, KnowledgeBase, Entity, Association, Workflow, WorkQueue, etc.)
  • scout-rig — language bridges (notably Python via PyCall)
  • scout-camp — remote servers, cloud deployments, web interfaces
  • scout-ai — LLMs, agents and model wrappers (this repository)

All packages are available under github.com/mikisvaz:

Scout originates from the Rbbt ecosystem (bioinformatics workflows). Numerous end‑to‑end examples live in the Rbbt‑Workflows organization:

The sections below summarize the main components (LLM, Chat, Agent, Model), quick starts, and the command‑line interface. For full APIs, see the doc/ directory.

  • doc/USER_GUIDE.md — practical first guide to endpoints, chat files, agents, workflow toolkits, and simple multi-agent patterns
  • doc/LLM.md — multi‑backend LLM orchestration, tool calling, endpoints, CLI
  • doc/Chat.md — chat files: roles/options, compilation pipeline, persistence
  • doc/Agent.md — stateful agents wired to Workflows and KnowledgeBases
  • python/README.md — Python SDK for Scout-AI chats and agents
  • doc/PythonAgentTasks.md — writing agent tasks in Python with PythonWorkflow auto-loading
  • doc/Model.md — model wrappers (ScoutModel, Python/Torch/Hugging Face)

Start here

If you are new to Scout-AI, use this order:

  1. doc/USER_GUIDE.md — first practical walkthrough
  2. doc/LLM.md — backend, endpoint, and CLI details
  3. doc/Chat.md — full chat role reference
  4. doc/Agent.md — stateful agents, tool wiring, delegation, workflow-backed ask
  5. python/README.md — use Scout-AI chats and agents from Python
  6. doc/PythonAgentTasks.md — package Python-backed tasks inside an agent directory

Installation and requirements

Scout is a Ruby framework. Add scout-ai (and the other packages you need) to your project and require as needed.

  • Ruby 3.x recommended
  • For Python‑backed models (Torch/Hugging Face):
    • Python 3 (installed and visible in PATH)
    • pycall gem (Ruby ↔ Python bridge)
    • Python packages: torch, transformers, numpy, pandas (as needed)
  • For OpenAI/Anthropic/etc backends: set API keys in environment or config (see doc/LLM.md)

Typical Gemfile fragment:

gem 'scout-essentials', git: 'https://github.com/mikisvaz/scout-essentials'
gem 'scout-gear',       git: 'https://github.com/mikisvaz/scout-gear'
gem 'scout-rig',        git: 'https://github.com/mikisvaz/scout-rig'
gem 'scout-ai',         git: 'https://github.com/mikisvaz/scout-ai'

Backends and endpoints can be configured via:

  • per-endpoint YAML files (recommended): ~/.scout/etc/AI/<endpoint>
  • environment variables per backend (see doc/LLM.md)

Most teams create a few named endpoints (e.g. nano, deep, ollama) and then reference them with:

  • Ruby: endpoint: :nano
  • CLI: -e nano

Quick starts

Configure an endpoint (once)

Create ~/.scout/etc/AI/nano:

backend: responses
model: gpt-5-nano

Or a higher-effort endpoint ~/.scout/etc/AI/deep:

backend: responses
model: gpt-5
reasoning_effort: high
text_verbosity: high

Keys beyond backend/url/model are passed through to the backend.

Ask a model

Ruby:

require 'scout-ai'
answer = LLM.ask "What is the capital of France?", endpoint: :nano
puts answer

CLI:

scout-ai llm ask -e nano "What is the capital of France?"

Chat builder:

chat = Chat.setup []
chat.system "You are a terse assistant"
chat.user   "List three colors"
puts chat.ask(endpoint: :nano)

Use Scout-AI from Python

The Python package under python/scout_ai is a thin wrapper around the Ruby runtime. It builds chats and agents in Python, but still uses Ruby for parsing, printing, and execution.

from scout_ai import load_agent

agent = load_agent("Planner", endpoint="nano")
agent.file("README.md")
agent.user("Summarize this repository")
message = agent.chat()
print(message.content)

See python/README.md for the Python-side API and doc/PythonAgentTasks.md for writing Python-backed workflow tasks.

Tool calling with a Workflow

Export Workflow tasks as callable tools—let the model call them functionally.

require 'scout-gear'  # defines Workflow

m = Module.new do
  extend Workflow
  self.name = "Registration"

  input :name, :string
  input :age, :integer
  input :gender, :select, nil, select_options: %w(male female)
  task :person => :yaml do
    inputs.to_hash
  end
end

puts LLM.workflow_ask(m, "Register Eduard Smith, a 25 yo male, using a tool call",
                      endpoint: :nano)

Stateful agent with a KnowledgeBase

require 'scout-gear'  # defines KnowledgeBase

TmpFile.with_dir do |dir|
  kb = KnowledgeBase.new dir
  kb.register :brothers, datafile_test(:person).brothers, undirected: true
  kb.register :marriages, datafile_test(:person).marriages,
             undirected: true, source: "=>Alias", target: "=>Alias"
  kb.register :parents, datafile_test(:person).parents

  agent = LLM::Agent.new(knowledge_base: kb, endpoint: :nano)
  agent.start
  agent.user "Who is Miki's brother in law?"
  puts agent.chat
end

Structured iteration

agent = LLM::Agent.new(endpoint: :nano)
agent.iterate("List three steps to bake bread") { |step| puts "- #{step}" }

agent.iterate_dictionary("Give capital cities for FR, ES, IT") do |country, capital|
  puts "#{country}: #{capital}"
end

Use a Hugging Face classifier inside a Workflow

From the ExTRI2 workflow (see below):

model = HuggingfaceModel.new 'SequenceClassification', tri_model_dir, nil,
  tokenizer_args: { model_max_length: 512, truncation: true },
  return_logits: true

model.extract_features do |_, rows|
  rows.map do |text, tf, tg|
    text.sub("[TF]", "<TF>#{tf}</TF>").sub("[TG]", "<TG>#{tg}</TG>")
  end
end

model.init
preds = model.eval_list tsv.slice(%w(Text TF Gene)).values
tsv.add_field "Valid score" do
  non_valid, valid = preds.shift
  Misc.softmax([valid, non_valid]).first rescue 0
end

Components overview

LLM (doc/LLM.md)

A compact, multi‑backend layer to ask LLMs, wire function‑calling tools, parse/print chats, and compute embeddings.

  • LLM.ask(question, options={}, &block) — compile question via LLM.chat, merge endpoint/model/format options, call backend
  • Backends: Responses, OpenAI, Anthropic, Ollama, vLLM, OpenWebUI, AWS Bedrock, Relay
  • Tools: export Workflow tasks and KnowledgeBase databases as function tools
  • Chat compilation pipeline: imports, clear/skip, tasks/jobs, files/directories
  • Endpoint configuration: ~/.scout/etc/AI/<endpoint>

Chat (doc/Chat.md)

Chat is both:

  • a builder over an Array of {role:, content:} messages
  • a stable on-disk “chat file” format used by the CLI

See doc/Chat.md for the full list of special roles (options, tools, imports, files, tasks, MCP, KB).

Agent (doc/Agent.md)

An Agent is a stateful wrapper around Chat and LLM:

  • maintains a current conversation (start_chat, start, current_chat)
  • auto-exports Workflow tasks and KnowledgeBase databases as tools
  • provides chat/json/json_format/iterate helpers

Model (doc/Model.md)

A composable framework to wrap models with a consistent API:

  • ScoutModel — base: define init/eval/eval_list/extract_features/post_process/train; persist behavior and state to a directory
  • PythonModel — initialize and drive a Python class via ScoutPython
  • TorchModel — helpers for PyTorch: training loop, tensors, save/load state, layer introspection
  • HuggingfaceModel — Transformers convenience; specializations:
    • SequenceClassificationModel — text classification, logits→labels
    • CausalModel — chat/causal generation (supports apply_chat_template)
    • NextTokenModel — simple next‑token fine‑tuning loop

Example: ExTRI2 workflow (models in practice)

The ExTRI2 Workflow (Rbbt‑Workflows) uses HuggingfaceModel to score TRI sentences and determine Mode of Regulation (MoR):

  • Feature extraction marks [TF]/[TG] spans as inline tags for the model
  • Batch evaluation over a TSV (“Text”, “TF”, “Gene” columns)
  • Adds fields “Valid score” and “Valid” to the TSV
  • Runs a second SequenceClassification model to produce “MoR” and “MoR scores”

See workflow.rb in that repository for the full implementation. http://github.com/Rbbt-Workflows/ExTRI2

Command‑Line Interface

The bin/scout dispatcher locates scripts under scout_commands across installed packages and workflows using the Path subsystem.

You can run it as:

  • scout ... (the standard Scout CLI), or
  • scout-ai ... (a thin wrapper that loads Scout with scout-ai available)

scout llm …

Ask an LLM, manage chat files, run a minimal web UI, or process queued requests. Scripts live under scout_commands/llm.

  • Ask

    • scout llm ask [options] [question]
    • scout-ai llm ask [options] [question]
    • -t|--template — load a prompt template; substitutes “???” or appends
    • -c|--chat — load/extend a conversation (appends the reply)
    • -i|--inline — answer “# ask: …” directives inline in a source file
    • -f|--file — prepend file content or substitute where “...” appears
    • -m|--model, -e|--endpoint, -b|--backend — select backend/model; merged with endpoint configs
    • -d|--dry_run — expand and print the conversation (no ask)

  • Relay processor (for the Relay backend)

    • scout llm process [directory] — watches a queue directory and answers ask JSONs

  • Web UI server

    • scout llm server — static chat UI over ./chats with a small JSON API

  • Templates

    • scout llm template — list installed prompt templates (Scout.questions)

Run scout llm alone to see available subcommands.

scout agent …

Stateful agents with Workflow and KnowledgeBase tooled up. Scripts live under scout_commands/agent.

  • Ask via an Agent

    • scout agent ask [options] [agent_name] [question]
    • scout-ai agent ask [options] [agent_name] [question]
    • -l|--log — set log severity
    • -t|--template
    • -c|--chat
    • -m|--model, -e|--endpoint
    • -f|--file
    • -wt|--workflow_tasks — export only selected tasks
    • agent_name resolves via Scout.workflowsagent_name or Scout.chatsagent_name

  • KnowledgeBase passthrough

    • scout agent kb <agent_name> <kb subcommand...>

Note: Workflows also have extensive CLI commands (scout workflow …) for job execution, provenance, orchestration, and queue processing.

Configuration, persistence and reproducibility

  • Endpoint presets: place YAML under ~/.scout/etc/AI/<endpoint> to preconfigure url/model/backend and backend-specific knobs
  • Tool calling: Workflow tasks are exported as JSON schemas per backend; results are serialized back to the model as tool replies
  • Caching: LLM.ask persists responses (by default) using Persist.persist; disable with persist: false
  • Chats: save printable conversations with Chat#save; reuse with scout-ai llm ask -c <file>

Where to go next

License and contributions

Issues and PRs are welcome across the Scout repositories. Please open tickets in the relevant package (e.g., scout-ai for LLM/Agent/Model topics).