scout-rig 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d34d9beba93482d6fdac2fae8ccf7c2a7dec45c36ed2a4f108887d9d32b98115
-  data.tar.gz: 6e47a0cf50320930b9781ece3496b17f9fcd62ad5f21b92ced385902392d5b48
+  metadata.gz: e217da5dacfbc60fa8f10fdeb62671ae53ecb74b537f422a61b9bdd0d68703a2
+  data.tar.gz: f8e6e1431abcc659d67f265270a114948c6d8f38e2430c03feb4ca35d9132ed2
 SHA512:
-  metadata.gz: 499c0b0c768e4ab955175244fb7ec5066503232d05bd2faf978aa5d4e8bcb364afe83b05b4e7d27f65e8c6ca3bdc225b96568d2d576992415832fee68f636b86
-  data.tar.gz: a30bcba9ce89f5f1622b89ffc0bd7a01971f4dbbba7c546321883e5d2ff74148a1529ab8dd044381b22f4ff98e64dce7fe3053f92a6e45f3f9a78dcd0be55b88
+  metadata.gz: c1a584e51e233aca2a640e9d4b9a5dc1dda24a96d17bad349d3d4e287d5e43a0a6e5092412dd0f9158cb88511266c5f4831f28788eccfc5aa94f2488e5c0b697
+  data.tar.gz: 28218f64da5fd31fe30ede23cb181cc9a9cd67fc5c768a7312672ac75321431125cf39be76df37511dbd2e5e62c6879f1cc0ffa10c2704f665c90ed2defa7438

data/.vimproject

@@ -3,6 +3,7 @@ scout-rig=/$PWD filter="*" {
  README.rdoc
  Rakefile
  chats=chats{
+
   documenter.rb
 
   python_workflow
@@ -39,7 +40,6 @@ scout-rig=/$PWD filter="*" {
  }
  python=python{
   task=task{
-   hello.py
   }
   test.py
   scout=scout{
@@ -47,9 +47,12 @@ scout-rig=/$PWD filter="*" {
    runner.py
    workflow.py
    workflow=workflow{
-    definition.py
     remote.py
    }
   }
  }
+ doc=doc{
+  Python.md
+  PythonWorkflow.md
+ }
 }

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/doc/PythonWorkflow.md

@@ -0,0 +1,163 @@
+PythonWorkflow lets you define Ruby Scout workflows whose tasks are implemented as standalone Python functions.
+
+This module is meant for workflow authors who prefer to write task logic in Python, while still benefiting from Scout/Rbbt features such as dependency management, persistence, provenance, and CLI integration.
+
+A Python-backed task is defined in a `.py` script (typically under a `python/task` directory). The script registers one or more functions using `scout.task(...)`. The Ruby workflow then calls `python_task` to import those function definitions as regular Scout tasks.
+
+Key ideas
+
+- Python tasks are ordinary Python functions with type hints, defaults, and a docstring.
+- The Python script can be run on its own:
+  - `--scout-metadata` prints machine-readable JSON task metadata (consumed by Ruby to define inputs and return types).
+  - without `--scout-metadata` it behaves like a CLI that runs the function.
+- Ruby side (`PythonWorkflow`) reads metadata and auto-creates Workflow inputs and tasks.
+- At execution time, the Ruby task block runs the Python script in a subprocess using `ScoutPython.run_file`.
+
+Minimal directory layout
+
+- `workflow.rb` defines the Ruby workflow.
+- `python/task/<name>.py` defines one or more Python functions and registers them.
+
+Example Python task
+
+```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)
+```
+
+Example Ruby workflow
+
+```ruby
+require 'scout'
+
+module TestPythonWF
+  extend Workflow
+  extend PythonWorkflow
+
+  self.name = 'TestPythonWF'
+
+  python_task :hello
+end
+```
+
+Type mapping (Python metadata to Scout inputs/returns)
+
+PythonWorkflow relies on `scout.task` metadata type strings (produced by `python/scout/runner.py`) and maps them to standard Workflow types.
+
+- Scalars
+  - `string` -> `:string`
+  - `integer` -> `:integer`
+  - `float` -> `:float`
+  - `boolean` -> `:boolean`
+  - `binary` -> `:binary`
+  - `path` -> `:file` for inputs (passed as a path string on the CLI)
+- Lists
+  - `list[string]`, `list[integer]`, `list[float]` -> `:array`
+  - `list[path]` -> `:file_array`
+
+List inputs in Ruby
+
+When building the Python command line, list parameters accept several Ruby-side formats:
+
+- A Ruby Array (`['a', 'b', 'c']`)
+- A comma-separated String (`"a,b,c"`)
+- A path to an existing file (the file is read line-by-line and passed as items)
+
+Return value decoding
+
+The Python runner prints function results to stdout, and Ruby tries to interpret them as follows:
+
+- If stdout is valid JSON, it is parsed with `JSON.parse` and returned.
+- Otherwise, if the declared Scout return type is `:array` or `:file_array`, stdout is split on newlines.
+- Otherwise, stdout is returned as a stripped string.
+
+This means you can return complex objects from Python, as long as the runner prints JSON and your declared return type can sensibly persist that Ruby value.
+
+Python CLI behavior (standalone execution)
+
+A Python task file registered via `scout.task(...)` can be used directly as a command-line tool.
+
+- Metadata:
+  - `python hello.py --scout-metadata`
+  - For files that register multiple functions, `--scout-metadata` prints a JSON array of metadata objects.
+- Run:
+  - `python hello.py --name Alice --excited`
+  - If multiple functions are registered in the same file, you can select one by passing its name as the first positional argument:
+    - `python tasks.py hello --name Alice`
+
+Python import paths
+
+Python tasks are executed as subprocesses with a `PYTHONPATH` composed from `ScoutPython.paths`. These are initialized from `Scout.python.find_all` and can be extended at runtime using `ScoutPython.add_path` or `ScoutPython.add_paths`.
+
+# Tasks
+
+## python_task
+Register one or more Python functions as Workflow tasks.
+
+`python_task` discovers and reads metadata from a Python script (by running it with `--scout-metadata`) and then defines one Workflow task per function found.
+
+Inputs and return type are inferred from the Python function signature and type hints.
+
+If the Python script registers multiple functions, multiple Workflow tasks are created (one per registered function). The `task_sym` argument selects the default filename to locate, but does not limit how many functions will be imported from that file.
+
+The task execution runs the Python script as a subprocess and passes CLI options that correspond to the declared inputs.
+
+## python_task_dir
+Configure where Python task scripts are discovered.
+
+By default, `python_task_dir` is taken from `Scout.python.task.find(:lib)`, so tasks can be shipped as part of a Scout package and located via the Path subsystem.
+
+You can override it by setting `self.python_task_dir` in your workflow module to a different Path or directory-like object that supports `[]` indexing and `find_with_extension('py')`.
+
+## scout.task
+Register a Python function as a Scout-compatible task and enable metadata/CLI execution.
+
+A Python task script should end with one or more `scout.task(function)` calls. This:
+
+- Captures signature, type hints, and docstring to build a metadata object.
+- Parses per-argument documentation primarily from Google-style `Args:` sections.
+- Enables `--scout-metadata` output for Ruby to consume.
+- Enables standalone CLI execution using argparse, including support for list and boolean arguments.
+
+For scripts that register multiple functions, `scout.task` defers CLI dispatch until interpreter shutdown so all functions are registered before selecting a target function.
+
+Docstring format for parameter descriptions
+
+To maximize interoperability with agent/tool frameworks and to provide good CLI help text, write docstrings in Google style.
+
+Recommended pattern:
+
+```python
+def my_task(query: str, max_results: int = 10) -> str:
+    """
+    Search items.
+
+    Args:
+        query: Natural language query describing what to search.
+        max_results: Maximum number of results to return.
+
+    Returns:
+        A newline-delimited or JSON-encoded result.
+    """
+```
+
+Notes:
+
+- The task description is taken from the docstring preamble: everything up to the first `Args:`/`Arguments:` or `Returns:` section.
+- The `Args:` section is used to populate each parameter `help` field in `--scout-metadata`.
+- Multi-line argument descriptions are supported as long as continuation lines stay indented.
+- A NumPy-style `Parameters` section is still accepted as a legacy fallback, but `Args:` is preferred.

data/lib/scout/workflow/python.rb

@@ -11,4 +11,24 @@ module PythonWorkflow
   def python_task_dir
     @python_task_dir ||= Scout.python.task.find(:lib) 
   end
+
+  def self.load_directory(path = nil, workflow_name = nil)
+    workflow = begin
+                   m = Module.new
+                   m.extend Workflow
+                   m.extend PythonWorkflow
+                   m.name = workflow_name || "PythonWorkflow"
+                   m.tasks = {}
+                   m
+                 end
+
+    path = Scout.python.task
+    workflow.python_task_dir = path
+    path.glob_names("*.py").each do |name|
+      name = name.sub '.py', ''
+      workflow.python_task name
+    end
+
+    workflow
+  end
 end

data/python/scout/runner.py

@@ -1,6 +1,7 @@
 import argparse
 import inspect
 import json
+import re
 import sys
 from pathlib import Path
 from typing import get_origin, get_args, Union, List
@@ -57,9 +58,118 @@ def _required_from_default(default_val, ann) -> bool:
 
 
 def _parse_numpy_params(doc: str) -> dict:
+    """
+    Extract per-parameter documentation from a docstring.
+
+    Despite the historical name, this parser prefers Google-style docstrings
+    ("Args:") because they map cleanly to tool schemas used by AI agents.
+
+    Supported formats:
+
+    Google style (recommended)::
+
+        Do something.
+
+        Args:
+            name: Description.
+            flag: Description that can wrap to
+                multiple indented lines.
+
+        Returns:
+            Description.
+
+    NumPy style (legacy fallback)::
+
+        Parameters
+        ----------
+        name : str
+            Description.
+
+    Returns:
+        dict mapping parameter name -> description string
+    """
+
     if not doc:
         return {}
+
     lines = doc.splitlines()
+
+    # -- Google style: Args: / Arguments: -----------------------------------
+    def parse_google_args() -> dict:
+        params = {}
+        i = 0
+        # Find section header
+        while i < len(lines):
+            header = lines[i].strip()
+            if header in ("Args:", "Arguments:"):
+                i += 1
+                break
+            i += 1
+        else:
+            return {}
+
+        # Parse items until next top-level section (Returns:, Raises:, etc.)
+        current = None
+        current_desc = []
+
+        def flush():
+            nonlocal current, current_desc
+            if current:
+                params[current] = " ".join(s.strip() for s in current_desc).strip()
+            current = None
+            current_desc = []
+
+        while i < len(lines):
+            raw = lines[i]
+            stripped = raw.strip()
+
+            # End conditions: next section header at left margin
+            if stripped.endswith(":") and not raw.startswith((" ", "\t")):
+                # Example: "Returns:", "Raises:", "Examples:", ...
+                break
+
+            # Skip empty lines between entries
+            if stripped == "":
+                if current is not None:
+                    current_desc.append("")
+                i += 1
+                continue
+
+            # Item start: indented "name:" or "name (type):"
+            # We require indentation so we don't confuse it with section headers.
+            if raw.startswith((" ", "\t")):
+                # Google-style param line (type is optional and ignored):
+                #   name: description
+                #   name (str): description
+                m = re.match(r"^\s*([A-Za-z_]\w*)\s*(?:\([^)]*\))?\s*:\s*(.*)$", stripped)
+                if m:
+                    param_name = m.group(1)
+                    first_desc = m.group(2).strip()
+
+                    if current and param_name != current:
+                        flush()
+                    if current is None:
+                        current = param_name
+                    if first_desc:
+                        current_desc.append(first_desc)
+                    i += 1
+                    continue
+
+            # Continuation line (more indented than the item header)
+            if current is not None:
+                current_desc.append(stripped)
+
+            i += 1
+
+        flush()
+        # Drop empty descriptions
+        return {k: v for k, v in params.items() if v is not None}
+
+    google = parse_google_args()
+    if google:
+        return google
+
+    # -- NumPy style fallback: Parameters / ---------- ----------------------
     params = {}
     i = 0
     while i < len(lines):
@@ -94,13 +204,54 @@ def _parse_numpy_params(doc: str) -> dict:
     return params
 
 
+def _extract_description(docstring: str) -> str:
+    """Extract a task description from a docstring.
+
+    The description is the full docstring preamble (potentially multiple lines
+    and paragraphs) up to the first schema-oriented section header.
+
+    This matches common conventions in LLM tool / JSON-schema extraction:
+    the preamble is the capability description, while sections like "Args:" and
+    "Returns:" provide structured schema information.
+    """
+
+    if not docstring:
+        return ""
+
+    stop_headers = {
+        # Google-style
+        "args:", "arguments:", "returns:", "raises:", "examples:", "example:",
+        "notes:", "note:",
+        # NumPy-style
+        "parameters", "returns", "raises", "examples", "notes",
+    }
+
+    out_lines = []
+    for line in docstring.splitlines():
+        stripped = line.strip()
+
+        # Stop at first recognized header line
+        if stripped and stripped.lower() in stop_headers:
+            break
+
+        out_lines.append(line.rstrip())
+
+    # Trim leading/trailing blank lines, preserve internal blank lines.
+    while out_lines and out_lines[0].strip() == "":
+        out_lines.pop(0)
+    while out_lines and out_lines[-1].strip() == "":
+        out_lines.pop()
+
+    return "\n".join(out_lines).strip()
+
+
 def describe_function(func) -> dict:
     sig = inspect.signature(func)
     doc = inspect.getdoc(func) or ""
     params_doc = _parse_numpy_params(doc)
 
     ret_type = _python_type_to_string(sig.return_annotation)
-    description = doc.split("\n\n", 1)[0] if doc else ""
+    description = _extract_description(doc)
 
     params = []
     for name, p in sig.parameters.items():

data/scout-rig.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-rig 0.2.1 ruby lib
+# stub: scout-rig 0.2.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "scout-rig".freeze
-  s.version = "0.2.1".freeze
+  s.version = "0.2.2".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
     "Rakefile",
     "VERSION",
     "doc/Python.md",
+    "doc/PythonWorkflow.md",
     "lib/scout-rig.rb",
     "lib/scout/python.rb",
     "lib/scout/python/paths.rb",
@@ -51,7 +52,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "http://github.com/mikisvaz/scout-rig".freeze
   s.licenses = ["MIT".freeze]
-  s.rubygems_version = "3.7.2".freeze
+  s.rubygems_version = "3.7.0.dev".freeze
   s.summary = "Scouts rigging things together".freeze
 
   s.specification_version = 4

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scout-rig
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Miguel Vazquez
@@ -52,6 +52,7 @@ files:
 - Rakefile
 - VERSION
 - doc/Python.md
+- doc/PythonWorkflow.md
 - lib/scout-rig.rb
 - lib/scout/python.rb
 - lib/scout/python/paths.rb
@@ -92,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.7.0.dev
 specification_version: 4
 summary: Scouts rigging things together
 test_files: []