scout-ai 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 456939ec51f2ea2c9be5a7fa5eb7992161e893dcfb6618b85eac7e7317af25fa
-  data.tar.gz: 67d22d1cd09f74c73843f143897d543993df4f5d68b9649ab1751a19a944e8fd
+  metadata.gz: 648a917e45f537ed44b068e1e4762a8a2846dbef5280cb9c37a0c2351e9e95b1
+  data.tar.gz: 25bf5fdbac1f713e6746a692f4aecefa594b69d6df17b526e4658182529a0b3a
 SHA512:
-  metadata.gz: 501bf9ff434058cb2ebad6b084a7ffbccf8a392b1a735c9e6e5726afcc23c7331ef471fc4c675130e49920def430332dd01b647b5f9a473c038b8ef0609d55e1
-  data.tar.gz: a267f504d6342a15fe1c0b7f180a47e3b7cd532b71fbd4a5fd3868b4fb7337f3a5c4f5d1ce0aa53276eb268e64ec035806d262b7713dba23d65bb50af2d6c3ab
+  metadata.gz: 6a46450a6d7e0b49b66cb2c0fe94efaa4ba8d4e030a607f8fd2da8a610af0143ae3272f04a470019e72d6b62e6510c7c291a75f1b70871ae3befeed87138237a
+  data.tar.gz: 2fe91febb6d59bca6fa3b942a4bd1fbade3f6001df35be85497e0020979de9c7642185bc8bb221a2f0edbe2872c41fbc24851805f47801425125d320a575e2c8

data/.vimproject

@@ -49,7 +49,7 @@ scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.
 
   test_prompt.rb
 
-  openclaw
+  from_python
  }
  lib=lib {
   scout-ai.rb
@@ -144,17 +144,21 @@ scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.
  python=python filter="*"{
   scout_ai=scout_ai{
    __init__.py
-   language_model.py
+   agent.py
+   chat.py
+   data.py
+   message.py
+   runner.py
    util.py
    huggingface=huggingface{
     data.py
     eval.py
     model.py
+    rlhf.py
     train=train{
      __init__.py
      next_token.py
     }
-    rlhf.py
    }
   }
  }
@@ -188,6 +192,7 @@ scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.
   documenter
   llm=llm{
    ask
+   json
    template
    process
    server
@@ -195,6 +200,7 @@ scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.
   agent=agent{
    ask
    kb
+   find
   }
  }
 }

data/VERSION

@@ -1 +1 @@
-1.2.1
+1.2.2

data/lib/scout/llm/agent.rb

@@ -10,7 +10,7 @@ module LLM
   end
 
   class Agent
-    attr_accessor :workflow, :knowledge_base, :start_chat, :process_exception, :other_options
+    attr_accessor :workflow, :knowledge_base, :start_chat, :process_exception, :other_options, :path
     def initialize(workflow: nil, knowledge_base: nil, start_chat: nil, **kwargs)
       @workflow = workflow
       @workflow = Workflow.require_workflow @workflow if String === @workflow
@@ -161,6 +161,7 @@ module LLM
       raise ScoutException, "No agent found with name #{agent_name}" unless workflow_path.exists? || agent_path.exists?
 
       workflow = if workflow_path.exists?
+                   agent_path = workflow_path
                    Workflow.require_workflow agent_name
                  elsif agent_path.workflow.find_with_extension("rb").exists?
                    Workflow.require_workflow_file agent_path.workflow.find_with_extension("rb")
@@ -185,7 +186,9 @@ module LLM
                Chat.setup([ {role: 'introduce', content: workflow.name} ])
              end
 
-      LLM::Agent.new **options.merge(workflow: workflow, knowledge_base: knowledge_base, start_chat: chat)
+      agent = LLM::Agent.new **options.merge(workflow: workflow, knowledge_base: knowledge_base, start_chat: chat)
+      agent.path = agent_path.find if agent_path
+      agent
     end
   end
 end

data/lib/scout/llm/chat/parse.rb

@@ -48,10 +48,10 @@ module Chat
         line = line.sub("]]", "")
         current_content << "\n" << line unless line.strip.empty?
         next
-      elsif stripped.match(/^.*:-- .* {{{/)
+      elsif stripped.match(/^[^\s]*:-- .* {{{/)
         in_protected_block = true
         protected_block_type = :square
-        line = line.sub(/^.*:-- (.*) {{{.*/, '<cmd_output cmd="\1">')
+        line = line.sub(/^[^\s]*:-- (.*) {{{.*/, '<cmd_output cmd="\1">')
         current_content << "\n" << line unless line.strip.empty?
         next
       elsif stripped.match(/^.*:--.* }}}/) && in_protected_block && protected_block_type == :square

data/python/scout_ai/__init__.py

@@ -1,35 +1,27 @@
-import scout
-import torch
-from .util import *
-
-class TSVDataset(torch.utils.data.Dataset):
-    def __init__(self, tsv):
-        self.tsv = tsv
-
-    def __getitem__(self, key):
-        if (type(key) == int):
-            row = self.tsv.iloc[key]
-        else:
-            row = self.tsv.loc[key]
-
-        row = row.to_numpy()
-        features = row[:-1]
-        label = row[-1]
-
-        return features, label
-
-    def __len__(self):
-        return len(self.tsv)
-
-def tsv_dataset(filename, *args, **kwargs):
-    return TSVDataset(scout.tsv(filename, *args, **kwargs))
-
-def tsv(*args, **kwargs):
-    return tsv_dataset(*args, **kwargs)
-
-def tsv_loader(*args, **kwargs):
-    dataset = tsv(*args, kwargs)
-    return torch.utils.data.DataLoader(dataset, batch_size=2, shuffle=True)
-
-def data_dir():
-    return scout.path('var/scout_dm/data')
+from .agent import Agent, load_agent
+from .chat import Chat
+from .message import Message
+from .runner import CommandError, ScoutRunner
+
+__all__ = [
+    "Agent",
+    "Chat",
+    "CommandError",
+    "Message",
+    "ScoutRunner",
+    "load_agent",
+]
+
+try:
+    from .util import deterministic, device, model_device, set_seed
+
+    __all__ += ["deterministic", "device", "model_device", "set_seed"]
+except Exception:
+    pass
+
+try:
+    from .data import TSVDataset, data_dir, tsv, tsv_dataset, tsv_loader
+
+    __all__ += ["TSVDataset", "data_dir", "tsv", "tsv_dataset", "tsv_loader"]
+except Exception:
+    pass

data/python/scout_ai/agent.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .chat import Chat
+from .runner import ScoutRunner
+
+
+class Agent:
+    """Thin Python wrapper over Scout-AI agents.
+
+    The object mirrors Scout-AI's ``start_chat`` / ``current_chat`` split while
+    delegating actual execution to the Ruby CLI.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        runner: Optional[ScoutRunner] = None,
+        start_chat: Optional[Chat] = None,
+        endpoint: Any = None,
+        model: Any = None,
+        backend: Any = None,
+        **options: Any,
+    ):
+        self.name = name
+        self.runner = runner or ScoutRunner()
+
+        if start_chat is None:
+            start_chat = Chat(self.runner.load_agent_start_chat(name), runner=self.runner)
+        elif not isinstance(start_chat, Chat):
+            start_chat = Chat(start_chat, runner=self.runner)
+        else:
+            start_chat.runner = self.runner
+
+        if endpoint is not None:
+            start_chat.endpoint(endpoint)
+        if model is not None:
+            start_chat.model(model)
+        if backend is not None:
+            start_chat.backend(backend)
+        for key, value in options.items():
+            if value is not None:
+                start_chat.option(key, value)
+
+        self.start_chat = start_chat
+        self.current_chat = self.start_chat.branch()
+
+    def start(self, chat: Optional[Chat] = None) -> Chat:
+        if chat is None:
+            self.current_chat = self.start_chat.branch()
+        elif isinstance(chat, Chat):
+            self.current_chat = chat.branch()
+            self.current_chat.runner = self.runner
+        else:
+            self.current_chat = Chat(chat, runner=self.runner)
+        return self.current_chat
+
+    reset = start
+
+    def ask(self) -> Chat:
+        return self.current_chat.ask(agent_name=self.name)
+
+    def chat(self):
+        delta = self.ask()
+        self.current_chat.extend(delta)
+        return delta.last_message()
+
+    def save(self, path, output_format: str = "chat"):
+        return self.current_chat.save(path, output_format=output_format)
+
+    def __getattr__(self, name: str):
+        attribute = getattr(self.current_chat, name)
+        if callable(attribute):
+            def delegated(*args, **kwargs):
+                result = attribute(*args, **kwargs)
+                if result is self.current_chat:
+                    return self
+                return result
+            return delegated
+        return attribute
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r}, current_chat={self.current_chat!r})"
+
+
+def load_agent(name: str, runner: Optional[ScoutRunner] = None, **kwargs: Any) -> Agent:
+    return Agent(name=name, runner=runner, **kwargs)

data/python/scout_ai/chat.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Sequence
+
+from .message import Message
+from .runner import ScoutRunner
+
+_RESERVED_MESSAGE_ROLES = {"previous_response_id"}
+
+
+class Chat:
+    """Python representation of a Scout chat.
+
+    The chat is kept as a list of messages. Whenever Scout needs to parse,
+    print, or execute the conversation, the package delegates that work to the
+    Ruby CLI through :class:`ScoutRunner`.
+    """
+
+    def __init__(self, messages: Optional[Iterable[dict | Message]] = None, runner: Optional[ScoutRunner] = None):
+        self.runner = runner or ScoutRunner()
+        self.messages: List[Message] = [Message.from_data(message) for message in (messages or [])]
+
+    @classmethod
+    def load(cls, path: str | Path, input_format: str = "chat", runner: Optional[ScoutRunner] = None) -> "Chat":
+        runner = runner or ScoutRunner()
+        messages = runner.load_messages(path, input_format=input_format)
+        return cls(messages, runner=runner)
+
+    @classmethod
+    def from_text(cls, text: str, runner: Optional[ScoutRunner] = None) -> "Chat":
+        runner = runner or ScoutRunner()
+        messages = runner.parse_chat_text(text)
+        return cls(messages, runner=runner)
+
+    def branch(self) -> "Chat":
+        return Chat([message.to_dict() for message in self.messages], runner=self.runner)
+
+    copy = branch
+
+    def to_dicts(self) -> List[Dict[str, Any]]:
+        return [message.to_dict() for message in self.messages]
+
+    def to_json(self) -> List[Dict[str, Any]]:
+        return self.to_dicts()
+
+    def render(self) -> str:
+        return self.runner.render_chat(self.to_dicts())
+
+    def save(self, path: str | Path, output_format: str = "chat") -> Path:
+        return self.runner.save_messages(path, self.to_dicts(), output_format=output_format)
+
+    def save_json(self, path: str | Path) -> Path:
+        return self.save(path, output_format="json")
+
+    def save_chat(self, path: str | Path) -> Path:
+        return self.save(path, output_format="chat")
+
+    def message(self, role: str, content: Any = "", **extra: Any) -> "Chat":
+        self.messages.append(Message(str(role), content, dict(extra)))
+        return self
+
+    def extend(self, messages: Iterable[dict | Message | "Chat"] | dict | Message | "Chat") -> "Chat":
+        if isinstance(messages, Chat):
+            iterable = messages.messages
+        elif isinstance(messages, (dict, Message)):
+            iterable = [messages]
+        else:
+            iterable = messages
+        for message in iterable:
+            self.messages.append(Message.from_data(message))
+        return self
+
+    append = extend
+
+    def user(self, content: Any) -> "Chat":
+        return self.message("user", content)
+
+    def system(self, content: Any) -> "Chat":
+        return self.message("system", content)
+
+    def assistant(self, content: Any) -> "Chat":
+        return self.message("assistant", content)
+
+    def import_(self, file: str | Path) -> "Chat":
+        return self.message("import", str(file))
+
+    def import_last(self, file: str | Path) -> "Chat":
+        return self.message("last", str(file))
+
+    def last(self, file: str | Path) -> "Chat":
+        return self.import_last(file)
+
+    def continue_(self, file: str | Path) -> "Chat":
+        return self.message("continue", str(file))
+
+    def file(self, file: str | Path) -> "Chat":
+        return self.message("file", str(file))
+
+    def directory(self, directory: str | Path) -> "Chat":
+        return self.message("directory", str(directory))
+
+    def image(self, file: str | Path) -> "Chat":
+        return self.message("image", str(file))
+
+    def pdf(self, file: str | Path) -> "Chat":
+        return self.message("pdf", str(file))
+
+    def introduce(self, workflow: str) -> "Chat":
+        return self.message("introduce", str(workflow))
+
+    def tool(self, *parts: Any) -> "Chat":
+        parts = [str(part) for part in parts if part is not None]
+        return self.message("tool", "\n".join(parts))
+
+    def use(self, *parts: Any) -> "Chat":
+        return self.tool(*parts)
+
+    def mcp(self, content: Any) -> "Chat":
+        return self.message("mcp", content)
+
+    def task(self, workflow: str, task_name: str, **inputs: Any) -> "Chat":
+        content = " ".join([str(workflow), str(task_name)] + [f"{key}={value}" for key, value in inputs.items()])
+        return self.message("task", content.strip())
+
+    def inline_task(self, workflow: str, task_name: str, **inputs: Any) -> "Chat":
+        content = " ".join([str(workflow), str(task_name)] + [f"{key}={value}" for key, value in inputs.items()])
+        return self.message("inline_task", content.strip())
+
+    def exec_task(self, workflow: str, task_name: str, **inputs: Any) -> "Chat":
+        content = " ".join([str(workflow), str(task_name)] + [f"{key}={value}" for key, value in inputs.items()])
+        return self.message("exec_task", content.strip())
+
+    def job(self, step: Any) -> "Chat":
+        value = getattr(step, "path", step)
+        return self.message("job", str(value))
+
+    def inline_job(self, step: Any) -> "Chat":
+        value = getattr(step, "path", step)
+        return self.message("inline_job", str(value))
+
+    def association(self, name: str, path: str | Path, **options: Any) -> "Chat":
+        parts = [str(name), str(path)] + [f"{key}={value}" for key, value in options.items()]
+        return self.message("association", " ".join(parts))
+
+    def option(self, name: str, value: Any) -> "Chat":
+        return self.message("option", f"{name} {value}")
+
+    def sticky_option(self, name: str, value: Any) -> "Chat":
+        return self.message("sticky_option", f"{name} {value}")
+
+    def endpoint(self, value: Any) -> "Chat":
+        return self.message("endpoint", value)
+
+    def model(self, value: Any) -> "Chat":
+        return self.message("model", value)
+
+    def backend(self, value: Any) -> "Chat":
+        return self.message("backend", value)
+
+    def format(self, value: Any) -> "Chat":
+        return self.message("format", value)
+
+    def persist(self, value: Any = True) -> "Chat":
+        return self.message("persist", value)
+
+    def previous_response_id(self, value: Any) -> "Chat":
+        return self.message("previous_response_id", value)
+
+    def clear(self, content: Any = "") -> "Chat":
+        return self.message("clear", content)
+
+    def skip(self, content: Any = "") -> "Chat":
+        return self.message("skip", content)
+
+    def answer(self) -> Optional[str]:
+        message = self.last_message()
+        if message is None:
+            return None
+        return message.content
+
+    def last_message(self, ignore_roles: Sequence[str] = tuple(_RESERVED_MESSAGE_ROLES)) -> Optional[Message]:
+        ignored = {str(role) for role in ignore_roles}
+        for message in reversed(self.messages):
+            if message.role not in ignored:
+                return message
+        return None
+
+    def _delta_from_updated_messages(self, updated_messages: Iterable[dict | Message]) -> "Chat":
+        old = self.to_dicts()
+        updated = [Message.from_data(message).to_dict() for message in updated_messages]
+
+        prefix_len = 0
+        for current, new in zip(old, updated):
+            if current == new:
+                prefix_len += 1
+            else:
+                break
+
+        return Chat(updated[prefix_len:], runner=self.runner)
+
+    def ask(self, agent_name: Optional[str] = None) -> "Chat":
+        updated_messages = self.runner.ask_messages(self.to_dicts(), agent_name=agent_name)
+        return self._delta_from_updated_messages(updated_messages)
+
+    def chat(self, agent_name: Optional[str] = None) -> Optional[Message]:
+        delta = self.ask(agent_name=agent_name)
+        self.extend(delta)
+        return delta.last_message()
+
+    def __len__(self) -> int:
+        return len(self.messages)
+
+    def __iter__(self) -> Iterator[Message]:
+        return iter(self.messages)
+
+    def __getitem__(self, item: int) -> Message:
+        return self.messages[item]
+
+    def __repr__(self) -> str:
+        return f"Chat(messages={self.messages!r})"

data/python/scout_ai/data.py

@@ -0,0 +1,39 @@
+import scout
+import torch
+
+
+class TSVDataset(torch.utils.data.Dataset):
+    def __init__(self, tsv):
+        self.tsv = tsv
+
+    def __getitem__(self, key):
+        if type(key) == int:
+            row = self.tsv.iloc[key]
+        else:
+            row = self.tsv.loc[key]
+
+        row = row.to_numpy()
+        features = row[:-1]
+        label = row[-1]
+
+        return features, label
+
+    def __len__(self):
+        return len(self.tsv)
+
+
+def tsv_dataset(filename, *args, **kwargs):
+    return TSVDataset(scout.tsv(filename, *args, **kwargs))
+
+
+def tsv(*args, **kwargs):
+    return tsv_dataset(*args, **kwargs)
+
+
+def tsv_loader(*args, **kwargs):
+    dataset = tsv(*args, kwargs)
+    return torch.utils.data.DataLoader(dataset, batch_size=2, shuffle=True)
+
+
+def data_dir():
+    return scout.path('var/scout_dm/data')

data/python/scout_ai/message.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping
+
+
+@dataclass
+class Message:
+    """Small wrapper around a Scout chat message.
+
+    Messages are still serialized as plain ``{"role": ..., "content": ...}``
+    dictionaries, but this wrapper makes the Python API easier to work with and
+    gives ``chat()`` a useful return value whose string representation is the
+    message content.
+    """
+
+    role: str
+    content: Any = ""
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_data(cls, data: Any) -> "Message":
+        if isinstance(data, cls):
+            return cls(data.role, data.content, dict(data.extra))
+
+        if isinstance(data, Mapping):
+            role = str(data.get("role", ""))
+            content = data.get("content", "")
+            extra = {k: v for k, v in data.items() if k not in ("role", "content")}
+            return cls(role=role, content=content, extra=extra)
+
+        raise TypeError(f"Unsupported message type: {type(data)!r}")
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {"role": self.role, "content": self.content}
+        data.update(self.extra)
+        return data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        if key == "role":
+            return self.role
+        if key == "content":
+            return self.content
+        return self.extra.get(key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "role":
+            return self.role
+        if key == "content":
+            return self.content
+        return self.extra[key]
+
+    def __str__(self) -> str:
+        return "" if self.content is None else str(self.content)
+
+    def __repr__(self) -> str:
+        return f"Message(role={self.role!r}, content={self.content!r})"

data/python/scout_ai/runner.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable, List, Optional, Sequence
+
+
+class CommandError(RuntimeError):
+    def __init__(self, cmd: Sequence[str], stdout: str, stderr: str, exit_status: int):
+        self.cmd = list(cmd)
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_status = exit_status
+        message = stderr.strip() or stdout.strip() or f"Command failed with exit status {exit_status}"
+        super().__init__(message)
+
+
+class ScoutRunner:
+    """Run Scout-AI CLI commands.
+
+    The Python package deliberately keeps Ruby as the source of truth for chat
+    parsing/printing and LLM execution. This runner is the bridge to those CLI
+    commands.
+    """
+
+    def __init__(self, command: Optional[Sequence[str] | str] = None):
+        if command is None:
+            command = os.environ.get("SCOUT_AI_COMMAND", "scout-ai")
+
+        if isinstance(command, str):
+            self.command = shlex.split(command)
+        else:
+            self.command = list(command)
+
+        if not self.command:
+            raise ValueError("command can not be empty")
+
+    def _run(self, *args: str) -> str:
+        cmd = self.command + [str(arg) for arg in args]
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise CommandError(cmd, proc.stdout, proc.stderr, proc.returncode)
+        return proc.stdout
+
+    def _write_json(self, path: Path, messages: Iterable[dict]) -> None:
+        path.write_text(json.dumps(list(messages), ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def json_to_chat_file(self, messages: Iterable[dict], chat_file: Path) -> Path:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False, encoding="utf-8") as handle:
+            json.dump(list(messages), handle, ensure_ascii=False, indent=2)
+            json_file = Path(handle.name)
+        try:
+            self._run("llm", "json", "--json", str(json_file), "--output", str(chat_file))
+        finally:
+            json_file.unlink(missing_ok=True)
+        return chat_file
+
+    def chat_file_to_messages(self, chat_file: Path) -> List[dict]:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False, encoding="utf-8") as handle:
+            json_file = Path(handle.name)
+        try:
+            self._run("llm", "json", "--chat", str(chat_file), "--output", str(json_file))
+            text = json_file.read_text(encoding="utf-8")
+            if text.strip() == "":
+                return []
+            return json.loads(text)
+        finally:
+            json_file.unlink(missing_ok=True)
+
+    def render_chat(self, messages: Iterable[dict]) -> str:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".chat", delete=False, encoding="utf-8") as handle:
+            chat_file = Path(handle.name)
+        try:
+            self.json_to_chat_file(messages, chat_file)
+            return chat_file.read_text(encoding="utf-8")
+        finally:
+            chat_file.unlink(missing_ok=True)
+
+    def parse_chat_text(self, text: str) -> List[dict]:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".chat", delete=False, encoding="utf-8") as handle:
+            handle.write(text)
+            chat_file = Path(handle.name)
+        try:
+            return self.chat_file_to_messages(chat_file)
+        finally:
+            chat_file.unlink(missing_ok=True)
+
+    def load_messages(self, path: str | Path, input_format: str = "chat") -> List[dict]:
+        path = Path(path)
+        if input_format == "json":
+            text = path.read_text(encoding="utf-8")
+            return [] if text.strip() == "" else json.loads(text)
+        if input_format != "chat":
+            raise ValueError(f"Unsupported input format: {input_format!r}")
+        return self.chat_file_to_messages(path)
+
+    def save_messages(self, path: str | Path, messages: Iterable[dict], output_format: str = "chat") -> Path:
+        path = Path(path)
+        if output_format == "json":
+            path.write_text(json.dumps(list(messages), ensure_ascii=False, indent=2), encoding="utf-8")
+            return path
+        if output_format != "chat":
+            raise ValueError(f"Unsupported output format: {output_format!r}")
+        self.json_to_chat_file(messages, path)
+        return path
+
+    def ask_messages(self, messages: Iterable[dict], agent_name: Optional[str] = None) -> List[dict]:
+        messages = list(messages)
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".chat", delete=False, encoding="utf-8") as handle:
+            chat_file = Path(handle.name)
+        try:
+            self.json_to_chat_file(messages, chat_file)
+            if agent_name:
+                self._run("agent", "ask", str(agent_name), "--chat", str(chat_file))
+            else:
+                self._run("llm", "ask", "--chat", str(chat_file))
+            return self.chat_file_to_messages(chat_file)
+        finally:
+            chat_file.unlink(missing_ok=True)
+
+    def find_agent_path(self, agent_name: str) -> Optional[Path]:
+        try:
+            output = self._run("agent", "find", str(agent_name)).strip()
+        except CommandError:
+            return None
+        if not output:
+            return None
+        return Path(output)
+
+    def load_agent_start_chat(self, agent_name: str) -> List[dict]:
+        path = self.find_agent_path(agent_name)
+        if path is None:
+            return []
+
+        if path.is_file():
+            try:
+                return self.load_messages(path, input_format="chat")
+            except Exception:
+                return []
+
+        candidates = [
+            path / "start_chat",
+            path / "start_chat.chat",
+            path / "start_chat.txt",
+        ]
+        candidates.extend(sorted(path.glob("start_chat.*")))
+
+        for candidate in candidates:
+            if candidate.exists() and candidate.is_file():
+                try:
+                    return self.load_messages(candidate, input_format="chat")
+                except Exception:
+                    continue
+
+        return []

data/python/tests/test_chat_agent.py

@@ -0,0 +1,67 @@
+import unittest
+
+from scout_ai import Chat, Message, load_agent
+
+
+class FakeRunner:
+    def ask_messages(self, messages, agent_name=None):
+        messages = list(messages)
+        label = agent_name or "llm"
+        return messages + [
+            {"role": "assistant", "content": f"reply from {label}"},
+            {"role": "previous_response_id", "content": f"resp-{label}"},
+        ]
+
+    def load_agent_start_chat(self, agent_name):
+        return [{"role": "system", "content": f"Agent {agent_name}"}]
+
+    def save_messages(self, path, messages, output_format="chat"):
+        return path
+
+
+class ChatAgentTest(unittest.TestCase):
+    def test_chat_ask_returns_only_new_messages(self):
+        runner = FakeRunner()
+        chat = Chat(runner=runner).system("You are concise").user("Hello")
+
+        delta = chat.ask()
+
+        self.assertEqual(len(chat), 2)
+        self.assertEqual(len(delta), 2)
+        self.assertEqual(delta[0].role, "assistant")
+        self.assertEqual(delta[0].content, "reply from llm")
+        self.assertEqual(delta[1].role, "previous_response_id")
+
+    def test_chat_chat_mutates_and_returns_last_meaningful_message(self):
+        runner = FakeRunner()
+        chat = Chat(runner=runner).user("Hello")
+
+        message = chat.chat()
+
+        self.assertIsInstance(message, Message)
+        self.assertEqual(message.role, "assistant")
+        self.assertEqual(str(message), "reply from llm")
+        self.assertEqual(len(chat), 3)
+        self.assertEqual(chat[-1].role, "previous_response_id")
+
+    def test_agent_eager_current_chat_and_delegation(self):
+        runner = FakeRunner()
+        agent = load_agent("Planner", runner=runner, endpoint="nano")
+
+        self.assertEqual(agent.start_chat[0].role, "system")
+        self.assertEqual(agent.start_chat[0].content, "Agent Planner")
+        self.assertEqual(agent.current_chat[1].role, "endpoint")
+        self.assertEqual(agent.current_chat[1].content, "nano")
+
+        agent.user("Summarize this")
+        self.assertEqual(len(agent.start_chat), 2)
+        self.assertEqual(len(agent.current_chat), 3)
+
+        message = agent.chat()
+        self.assertEqual(message.role, "assistant")
+        self.assertEqual(message.content, "reply from Planner")
+        self.assertEqual(agent.current_chat[-1].role, "previous_response_id")
+
+
+if __name__ == "__main__":
+    unittest.main()

data/scout-ai.gemspec

@@ -2,11 +2,11 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: scout-ai 1.2.1 ruby lib
+# stub: scout-ai 1.2.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "scout-ai".freeze
-  s.version = "1.2.1".freeze
+  s.version = "1.2.2".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -86,18 +86,26 @@ Gem::Specification.new do |s|
     "lib/scout/network/knowledge_base.rb",
     "lib/scout/network/paths.rb",
     "python/scout_ai/__init__.py",
+    "python/scout_ai/agent.py",
+    "python/scout_ai/chat.py",
+    "python/scout_ai/data.py",
     "python/scout_ai/huggingface/data.py",
     "python/scout_ai/huggingface/eval.py",
     "python/scout_ai/huggingface/model.py",
     "python/scout_ai/huggingface/rlhf.py",
     "python/scout_ai/huggingface/train/__init__.py",
     "python/scout_ai/huggingface/train/next_token.py",
+    "python/scout_ai/message.py",
+    "python/scout_ai/runner.py",
     "python/scout_ai/util.py",
+    "python/tests/test_chat_agent.py",
     "scout-ai.gemspec",
     "scout_commands/agent/ask",
+    "scout_commands/agent/find",
     "scout_commands/agent/kb",
     "scout_commands/documenter",
     "scout_commands/llm/ask",
+    "scout_commands/llm/json",
     "scout_commands/llm/process",
     "scout_commands/llm/server",
     "scout_commands/llm/template",

data/scout_commands/agent/ask

@@ -10,7 +10,7 @@ $0 = "scout #{$previous_commands.any? ? $previous_commands*" " + " " : "" }#{ Fi
 
 options = SOPT.setup <<EOF
 
-Ask GPT
+Ask an Agent
 
 $ #{$0} [<options>] [question]
 

data/scout_commands/agent/find

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+require 'scout'
+require 'scout-ai'
+
+$0 = "scout #{$previous_commands.any? ? $previous_commands*" " + " " : "" }#{ File.basename(__FILE__) }" if $previous_commands
+
+options = SOPT.setup <<EOF
+
+Find an Agent
+
+$ #{$0} [<options>]
+
+-h--help Print this help
+EOF
+if options[:help]
+  if defined? scout_usage
+    scout_usage 
+  else
+    puts SOPT.doc
+  end
+  exit 0
+end
+
+Log.severity = options.delete(:log).to_i if options.include? :log
+
+agent_name, *question_parts = ARGV
+
+agent = LLM.load_agent agent_name, options
+
+puts agent.path

data/scout_commands/llm/json

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'scout'
+
+cmd = $previous_commands ?
+  "scout #{$previous_commands.any? ? "#{$previous_commands * ' '} " : ''}#{File.basename(__FILE__)}" :
+  $PROGRAM_NAME
+
+options = SOPT.setup <<~EOF
+
+Translate chats to and from json format
+
+$ #{cmd} [<options>] <filename>
+
+Reads the file as JSON or Chat format and prints it in the oposite format.
+Use `--chat` and `--json` to speciy the format on the input. Use
+the `output` flag to save it to a file.
+
+-h--help This help
+-c--chat Load as Chat format
+-j--json Load as JSON format (Default)
+-o--output* Save to file instead of printing to STDOUT
+
+EOF
+if options[:help]
+  if defined? scout_usage
+    scout_usage
+  else
+    puts SOPT.doc
+  end
+  exit 0
+end
+
+help = IndiferentHash.process_options options, :help
+
+filename,  _ = ARGV
+
+raise MissingParameterException, :filename if filename.nil?
+
+raise ParameterException, "Don't use the json and chat flags at the same time, only the one that corresponds to the input file fomat" if options[:chat] && options[:json]
+
+input = :json unless options[:chat]
+
+if input == :json
+  messages = Chat.setup(Open.json(filename))
+else
+  messages = LLM.chat(filename)
+end
+
+if input == :json
+  str = LLM.print messages
+else
+  str = messages.to_json
+end
+
+if options[:output]
+  Open.write(options[:output], str)
+else
+  puts str
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scout-ai
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Miguel Vazquez
@@ -154,18 +154,26 @@ files:
 - lib/scout/network/knowledge_base.rb
 - lib/scout/network/paths.rb
 - python/scout_ai/__init__.py
+- python/scout_ai/agent.py
+- python/scout_ai/chat.py
+- python/scout_ai/data.py
 - python/scout_ai/huggingface/data.py
 - python/scout_ai/huggingface/eval.py
 - python/scout_ai/huggingface/model.py
 - python/scout_ai/huggingface/rlhf.py
 - python/scout_ai/huggingface/train/__init__.py
 - python/scout_ai/huggingface/train/next_token.py
+- python/scout_ai/message.py
+- python/scout_ai/runner.py
 - python/scout_ai/util.py
+- python/tests/test_chat_agent.py
 - scout-ai.gemspec
 - scout_commands/agent/ask
+- scout_commands/agent/find
 - scout_commands/agent/kb
 - scout_commands/documenter
 - scout_commands/llm/ask
+- scout_commands/llm/json
 - scout_commands/llm/process
 - scout_commands/llm/server
 - scout_commands/llm/template