scout-ai 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 648a917e45f537ed44b068e1e4762a8a2846dbef5280cb9c37a0c2351e9e95b1
-  data.tar.gz: 25bf5fdbac1f713e6746a692f4aecefa594b69d6df17b526e4658182529a0b3a
+  metadata.gz: 8549d8d309d5c6fa5b4b259db26ac7001cafa2fd10b99fe552e6f733a8a8d72e
+  data.tar.gz: 52f728fa8fd19b5c6bc6a4f2ec8245241345946ffe682a8d54ba89dd4a61ca14
 SHA512:
-  metadata.gz: 6a46450a6d7e0b49b66cb2c0fe94efaa4ba8d4e030a607f8fd2da8a610af0143ae3272f04a470019e72d6b62e6510c7c291a75f1b70871ae3befeed87138237a
-  data.tar.gz: 2fe91febb6d59bca6fa3b942a4bd1fbade3f6001df35be85497e0020979de9c7642185bc8bb221a2f0edbe2872c41fbc24851805f47801425125d320a575e2c8
+  metadata.gz: 884c4612317b94f3511118c62a03d5a665f42107ebdeb233d13618bd22e23b97aa290025d054c5b11683334570a870fbdab6a75f662dca3d5639d54d383fb7d6
+  data.tar.gz: f7c59e09e5e0f6052204033d23de97f1202eb762ee548aee5caac63081d69f8f9fcd5c5170a99e76ad73c8d2b99578c5ddda7ee8897ced9dc6f09f7fafac6e00

data/.vimproject

@@ -1,5 +1,6 @@
 scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.txt *.conf" {
  README.md
+ Rakefile
  chats=chats filter="*"{
   system=system{
    scout-ai
@@ -50,6 +51,12 @@ scout-ai=$PWD filter="*.rb *.rake Rakefile *.rdoc *.R *.sh *.js *.haml *.sass *.
   test_prompt.rb
 
   from_python
+
+  python_delegation
+
+  python_package
+
+  stderr_python
  }
  lib=lib {
   scout-ai.rb

data/VERSION

@@ -1 +1 @@
-1.2.2
+1.2.3

data/lib/scout/llm/chat/process/tools.rb

@@ -109,8 +109,10 @@ module Chat
 
   def self.tools(messages)
     tool_definitions = IndiferentHash.setup({})
+    introduced_workflows = []
     new = messages.collect do |message|
-      if message[:role] == 'mcp'
+      role = message[:role]
+      if role == 'mcp'
         url, *tools = content_tokens(message)
 
         if url == 'stdio'
@@ -128,7 +130,7 @@ module Chat
           tool_definitions.merge!(mcp_tool_definitions)
         end
         next
-      elsif message[:role] == 'tool'
+      elsif role == 'tool'
         workflow_name, task_name, *inputs = content_tokens(message)
         inputs = nil if inputs.empty?
         inputs = [] if inputs == ['none'] || inputs == ['noinputs']
@@ -148,8 +150,10 @@ module Chat
           tool_definitions.merge!(LLM.workflow_tools(workflow))
         end
         next
-      elsif message[:role] == 'introduce'
+      elsif role == 'introduce'
         workflow_name = message[:content]
+        next if introduced_workflows.include? workflow_name
+        introduced_workflows << workflow_name
         workflow = begin
                      Kernel.const_get workflow_name
                    rescue
@@ -176,7 +180,7 @@ Below is the documentation of the workflow:
         EOF
 
         {role: :user, content: content}
-      elsif message[:role] == 'kb'
+      elsif role == 'kb'
         knowledge_base_name, *databases = content_tokens(message)
         databases = nil if databases.empty?
         knowledge_base = KnowledgeBase.load knowledge_base_name
@@ -184,7 +188,7 @@ Below is the documentation of the workflow:
         knowledge_base_definition = LLM.knowledge_base_tool_definition(knowledge_base, databases)
         tool_definitions.merge!(knowledge_base_definition)
         next
-      elsif message[:role] == 'clear_tools'
+      elsif role == 'clear_tools'
         tool_definitions = {}
       else
         message
@@ -197,7 +201,8 @@ Below is the documentation of the workflow:
   def self.associations(messages, kb = nil)
     tool_definitions = {}
     new = messages.collect do |message|
-      if message[:role] == 'association'
+      role = message[:role]
+      if role == 'association'
         name, path, *options = content_tokens(message)
 
         kb ||= KnowledgeBase.new Scout.var.Agent.Chat.knowledge_base
@@ -205,7 +210,7 @@ Below is the documentation of the workflow:
 
         tool_definitions.merge!(LLM.knowledge_base_tool_definition( kb, [name]))
         next
-      elsif message[:role] == 'clear_associations'
+      elsif role == 'clear_associations'
         tool_definitions = {}
       else
         message

data/python/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+build/
+dist/
+.pytest_cache/

data/python/README.md

@@ -0,0 +1,91 @@
+# scout-ai Python package
+
+This directory contains the Python package for Scout-AI.
+
+The package provides a lightweight Python interface to Scout-AI chats and agents while keeping Ruby as the source of truth for:
+
+- chat parsing and printing
+- LLM execution
+- agent execution
+- workflow and tool execution
+
+In practice, the Python layer builds chat objects, serializes them through the Scout-AI CLI, and delegates execution back to Scout.
+
+## Requirements
+
+The Python package expects the `scout-ai` command to be available.
+
+Usually this means you should already have the Ruby Scout-AI package installed and configured, together with the Scout stack it depends on.
+
+If the command is not on your `PATH`, you can point the Python package to it with:
+
+    export SCOUT_AI_COMMAND=/full/path/to/scout-ai
+
+## Install from GitHub with pip
+
+Because this repository is primarily a Ruby project and the Python package lives under `python/`, install it with the `subdirectory` fragment:
+
+    pip install "scout-ai @ git+https://github.com/mikisvaz/scout-ai.git@main#subdirectory=python"
+
+You can also omit the explicit package name:
+
+    pip install "git+https://github.com/mikisvaz/scout-ai.git@main#subdirectory=python"
+
+For editable local development from a clone of the repository:
+
+    pip install -e python
+
+## Optional extras
+
+If you also want the machine-learning helpers, you can install optional extras:
+
+    pip install "scout-ai[ml] @ git+https://github.com/mikisvaz/scout-ai.git@main#subdirectory=python"
+
+For Hugging Face / RLHF helpers:
+
+    pip install "scout-ai[huggingface] @ git+https://github.com/mikisvaz/scout-ai.git@main#subdirectory=python"
+
+## Quick example
+
+    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)
+
+## Chat example
+
+    from scout_ai import Chat
+
+    chat = Chat()
+    chat.system("You are concise")
+    chat.user("Say hello")
+
+    delta = chat.ask()
+    print(delta.to_json())
+
+## What pip installs
+
+The pip package installs only the Python interface contained in this directory.
+It does not install the Ruby Scout-AI gem or the rest of the Scout stack.
+
+That separation is intentional:
+
+- Ruby remains responsible for the actual Scout-AI runtime
+- Python provides an ergonomic interface to that runtime
+
+## Package layout
+
+- `scout_ai.chat.Chat` — chat builder and execution wrapper
+- `scout_ai.agent.Agent` — thin wrapper over Scout agents with eager `current_chat`
+- `scout_ai.runner.ScoutRunner` — CLI bridge used internally
+- `scout_ai.message.Message` — message wrapper returned by `chat()`
+
+## Running tests
+
+From the repository root:
+
+    PYTHONPATH=python python -m unittest discover python/tests

data/python/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scout-ai"
+version = "1.2.2"
+description = "Python interface for Scout-AI chats, agents, and model helpers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Miki S. Vazquez" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = []
+
+[project.optional-dependencies]
+ml = [
+  "numpy",
+  "pandas",
+  "torch"
+]
+huggingface = [
+  "datasets",
+  "transformers",
+  "trl"
+]
+
+[project.urls]
+Homepage = "https://github.com/mikisvaz/scout-ai"
+Repository = "https://github.com/mikisvaz/scout-ai"
+Issues = "https://github.com/mikisvaz/scout-ai/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scout_ai*"]
+
+[tool.setuptools]
+include-package-data = true

data/python/scout_ai/runner.py

@@ -4,9 +4,11 @@ import json
 import os
 import shlex
 import subprocess
+import sys
 import tempfile
+import threading
 from pathlib import Path
-from typing import Any, Iterable, List, Optional, Sequence
+from typing import Iterable, List, Optional, Sequence, TextIO
 
 
 class CommandError(RuntimeError):
@@ -27,7 +29,12 @@ class ScoutRunner:
     commands.
     """
 
-    def __init__(self, command: Optional[Sequence[str] | str] = None):
+    def __init__(
+        self,
+        command: Optional[Sequence[str] | str] = None,
+        show_stderr: bool = True,
+        stderr: Optional[TextIO] = None,
+    ):
         if command is None:
             command = os.environ.get("SCOUT_AI_COMMAND", "scout-ai")
 
@@ -39,15 +46,49 @@ class ScoutRunner:
         if not self.command:
             raise ValueError("command can not be empty")
 
-    def _run(self, *args: str) -> str:
+        self.show_stderr = show_stderr
+        self.stderr = stderr
+
+    def _run(self, *args: str, stream_stderr: bool = False) -> 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")
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+
+        stdout_chunks: List[str] = []
+        should_stream = stream_stderr and self.show_stderr
+        stderr_target = self.stderr if self.stderr is not None else sys.stderr
+
+        def forward_stderr() -> None:
+            assert proc.stderr is not None
+            while True:
+                chunk = proc.stderr.readline()
+                if chunk == "":
+                    break
+                if should_stream:
+                    stderr_target.write(chunk)
+                    stderr_target.flush()
+
+        stderr_thread = threading.Thread(target=forward_stderr, daemon=True)
+        stderr_thread.start()
+
+        assert proc.stdout is not None
+        stdout_chunks.append(proc.stdout.read())
+        proc.stdout.close()
+
+        stderr_thread.join()
+        returncode = proc.wait()
+
+        stdout = "".join(stdout_chunks)
+
+        if returncode != 0:
+            raise CommandError(cmd, stdout, "", returncode)
+        return stdout
 
     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:
@@ -115,9 +156,9 @@ class ScoutRunner:
         try:
             self.json_to_chat_file(messages, chat_file)
             if agent_name:
-                self._run("agent", "ask", str(agent_name), "--chat", str(chat_file))
+                self._run("agent", "ask", str(agent_name), "--chat", str(chat_file), stream_stderr=True)
             else:
-                self._run("llm", "ask", "--chat", str(chat_file))
+                self._run("llm", "ask", "--chat", str(chat_file), stream_stderr=True)
             return self.chat_file_to_messages(chat_file)
         finally:
             chat_file.unlink(missing_ok=True)

data/python/tests/test_runner.py

@@ -0,0 +1,27 @@
+import io
+import sys
+import unittest
+from contextlib import redirect_stderr
+
+from scout_ai.runner import ScoutRunner
+
+
+class RunnerStreamingTest(unittest.TestCase):
+    def test_run_streams_stderr_when_requested(self):
+        code = (
+            "import sys; "
+            "sys.stderr.write('waiting...\\n'); sys.stderr.flush(); "
+            "print('done')"
+        )
+        runner = ScoutRunner(command=[sys.executable, "-c", code])
+
+        stderr = io.StringIO()
+        with redirect_stderr(stderr):
+            output = runner._run("ignored", stream_stderr=True)
+
+        self.assertEqual(output.strip(), "done")
+        self.assertIn("waiting...", stderr.getvalue())
+
+
+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.2 ruby lib
+# stub: scout-ai 1.2.3 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "scout-ai".freeze
-  s.version = "1.2.2".freeze
+  s.version = "1.2.3".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -85,6 +85,9 @@ Gem::Specification.new do |s|
     "lib/scout/network/entity.rb",
     "lib/scout/network/knowledge_base.rb",
     "lib/scout/network/paths.rb",
+    "python/.gitignore",
+    "python/README.md",
+    "python/pyproject.toml",
     "python/scout_ai/__init__.py",
     "python/scout_ai/agent.py",
     "python/scout_ai/chat.py",
@@ -99,6 +102,7 @@ Gem::Specification.new do |s|
     "python/scout_ai/runner.py",
     "python/scout_ai/util.py",
     "python/tests/test_chat_agent.py",
+    "python/tests/test_runner.py",
     "scout-ai.gemspec",
     "scout_commands/agent/ask",
     "scout_commands/agent/find",
@@ -156,7 +160,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "http://github.com/mikisvaz/scout-ai".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.7.0.dev".freeze
+  s.rubygems_version = "3.7.2".freeze
   s.summary = "AI gear for scouts".freeze
 
   s.specification_version = 4

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scout-ai
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors:
 - Miguel Vazquez
@@ -153,6 +153,9 @@ files:
 - lib/scout/network/entity.rb
 - lib/scout/network/knowledge_base.rb
 - lib/scout/network/paths.rb
+- python/.gitignore
+- python/README.md
+- python/pyproject.toml
 - python/scout_ai/__init__.py
 - python/scout_ai/agent.py
 - python/scout_ai/chat.py
@@ -167,6 +170,7 @@ files:
 - python/scout_ai/runner.py
 - python/scout_ai/util.py
 - python/tests/test_chat_agent.py
+- python/tests/test_runner.py
 - scout-ai.gemspec
 - scout_commands/agent/ask
 - scout_commands/agent/find
@@ -239,7 +243,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0.dev
+rubygems_version: 3.7.2
 specification_version: 4
 summary: AI gear for scouts
 test_files: []