pyoco 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

pyoco/__init__.py

@@ -2,10 +2,11 @@ from .core.models import Flow, Task
 from .core.engine import Engine
 from .dsl.syntax import task
 from .trace.console import ConsoleTraceBackend
+from . import support
 
 def run(flow: Flow, params: dict = None, trace: bool = True, cute: bool = True):
     backend = ConsoleTraceBackend(style="cute" if cute else "plain")
     engine = Engine(trace_backend=backend)
     return engine.run(flow, params)
 
-__all__ = ["task", "Flow", "run"]
+__all__ = ["task", "Flow", "run", "support"]

pyoco/cli/main.py

@@ -4,13 +4,22 @@ import sys
 import os
 import signal
 import time
+from types import SimpleNamespace
 from ..schemas.config import PyocoConfig
 from ..discovery.loader import TaskLoader
 from ..core.models import Flow
 from ..core.engine import Engine
 from ..trace.console import ConsoleTraceBackend
 from ..client import Client
-from ..discovery.plugins import list_available_plugins
+from ..support.service import SupportInfoService
+from ..core.exceptions import (
+    SupportInfoError,
+    InvalidFormatError,
+    TaskNotFoundError,
+    InvalidFilterError,
+    OutputWriteError,
+    MissingTaskMetadataError,
+)
 
 def main():
     parser = argparse.ArgumentParser(description="Pyoco Workflow Engine")
@@ -88,6 +97,32 @@ def main():
     plugins_sub = plugins_parser.add_subparsers(dest="plugins_command")
     plugins_list = plugins_sub.add_parser("list", help="List discovered plug-ins")
     plugins_list.add_argument("--json", action="store_true", help="Output JSON payload")
+    plugins_lint = plugins_sub.add_parser("lint", help="Validate plug-ins for upcoming requirements")
+    plugins_lint.add_argument("--json", action="store_true", help="Output JSON payload")
+
+    support_parser = subparsers.add_parser("support", help="Generate support info")
+    support_subparsers = support_parser.add_subparsers(dest="support_command")
+
+    support_tasks = support_subparsers.add_parser("tasks", help="List tasks for LLM support")
+    support_tasks.add_argument("--config", required=True, help="Path to flow.yaml")
+    support_tasks.add_argument("--format", default="prompt", choices=["prompt", "json", "md"])
+    support_tasks.add_argument("--output", help="Write output to file")
+    support_tasks.add_argument("--name", action="append", help="Filter by task name (repeatable)")
+    support_tasks.add_argument("--origin", action="append", help="Filter by origin (repeatable)")
+    support_tasks.add_argument("--tag", action="append", help="Filter by tag (repeatable)")
+
+    support_task = support_subparsers.add_parser("task", help="Show task detail for LLM support")
+    support_task.add_argument("--config", required=True, help="Path to flow.yaml")
+    support_task.add_argument("--name", required=True, help="Task name")
+    support_task.add_argument("--format", default="prompt", choices=["prompt", "json", "md"])
+    support_task.add_argument("--output", help="Write output to file")
+    support_task.add_argument("--origin", action="append", help="Filter by origin (repeatable)")
+    support_task.add_argument("--tag", action="append", help="Filter by tag (repeatable)")
+
+    support_guide = support_subparsers.add_parser("guide", help="Show flow.yaml guide for LLM support")
+    support_guide.add_argument("--config", required=True, help="Path to flow.yaml")
+    support_guide.add_argument("--format", default="prompt", choices=["prompt", "json", "md"])
+    support_guide.add_argument("--output", help="Write output to file")
 
     args = parser.parse_args()
 
@@ -120,18 +155,72 @@ def main():
         return
 
     if args.command == "plugins":
-        infos = list_available_plugins()
+        reports = _collect_plugin_reports()
         if args.plugins_command == "list":
             if getattr(args, "json", False):
-                print(json.dumps(infos, indent=2))
+                print(json.dumps(reports, indent=2))
             else:
-                if not infos:
+                if not reports:
                     print("No plug-ins registered under group 'pyoco.tasks'.")
                 else:
                     print("Discovered plug-ins:")
-                    for info in infos:
+                    for info in reports:
                         mod = info.get("module") or info.get("value")
                         print(f" - {info.get('name')} ({mod})")
+                        if info.get("error"):
+                            print(f"     ⚠️  error: {info['error']}")
+                            continue
+                        for task in info.get("tasks", []):
+                            warn_msg = "; ".join(task.get("warnings", [])) or "ok"
+                            print(f"     • {task['name']} [{task['origin']}] ({warn_msg})")
+                        for warn in info.get("warnings", []):
+                            print(f"     ⚠️  {warn}")
+        elif args.plugins_command == "lint":
+            issues = []
+            for info in reports:
+                prefix = info["name"]
+                if info.get("error"):
+                    issues.append(f"{prefix}: {info['error']}")
+                    continue
+                for warn in info.get("warnings", []):
+                    issues.append(f"{prefix}: {warn}")
+                for task in info.get("tasks", []):
+                    for warn in task.get("warnings", []):
+                        issues.append(f"{prefix}.{task['name']}: {warn}")
+            payload = {"issues": issues, "reports": reports}
+            if getattr(args, "json", False):
+                print(json.dumps(payload, indent=2))
+            else:
+                if not issues:
+                    print("✅ All plug-ins look good.")
+                else:
+                    print("⚠️  Plug-in issues found:")
+                    for issue in issues:
+                        print(f" - {issue}")
+            if issues:
+                sys.exit(1)
+        else:
+            plugins_parser.print_help()
+        return
+
+    if args.command == "support":
+        if not args.support_command:
+            support_parser.print_help()
+            sys.exit(1)
+        filters = _build_support_filters(args)
+        try:
+            content = SupportInfoService().build(
+                kind=args.support_command,
+                config_path=args.config,
+                format=args.format,
+                filters=filters or None,
+                output_path=args.output,
+            )
+        except SupportInfoError as exc:
+            _print_support_error(exc)
+            sys.exit(1)
+        if not args.output:
+            print(content)
         return
 
     if args.command == "server":
@@ -368,6 +457,45 @@ def main():
             sys.exit(2 if args.dry_run else 1)
         return
 
+def _collect_plugin_reports():
+    dummy = SimpleNamespace(tasks={})
+    loader = TaskLoader(dummy)
+    loader.load()
+    return loader.plugin_reports
+
+
+def _build_support_filters(args):
+    filters = {}
+    if getattr(args, "name", None):
+        value = args.name
+        filters["name"] = value if isinstance(value, list) else [value]
+    if getattr(args, "origin", None):
+        filters["origin"] = args.origin
+    if getattr(args, "tag", None):
+        filters["tag"] = args.tag
+    return filters
+
+
+def _print_support_error(exc: SupportInfoError) -> None:
+    if isinstance(exc, InvalidFormatError):
+        print(f"Invalid format: {exc.format}")
+        return
+    if isinstance(exc, TaskNotFoundError):
+        print(f"Task not found: {exc.name}")
+        return
+    if isinstance(exc, OutputWriteError):
+        print(f"Failed to write output: {exc.path}")
+        return
+    if isinstance(exc, InvalidFilterError):
+        print(f"Invalid filter: {exc.filter_value}")
+        return
+    if isinstance(exc, MissingTaskMetadataError):
+        fields = ",".join(exc.fields)
+        print(f"Missing task metadata: {exc.name} fields={fields}")
+        return
+    print(f"Error: {exc}")
+
+
 def _stream_logs(client, args):
     seen_seq = -1
     follow = args.follow

pyoco/core/exceptions.py

@@ -13,3 +13,39 @@ class SwitchNoMatch(ControlFlowError):
     def __init__(self, expression: str):
         super().__init__(f"Switch expression '{expression}' did not match any case.")
         self.expression = expression
+
+
+class SupportInfoError(Exception):
+    """Base error for support info generation."""
+
+
+class InvalidFormatError(SupportInfoError):
+    def __init__(self, format: str):
+        self.format = format
+        super().__init__(f"Invalid format: {format}")
+
+
+class TaskNotFoundError(SupportInfoError):
+    def __init__(self, name: str):
+        self.name = name
+        super().__init__(f"Task not found: {name}")
+
+
+class InvalidFilterError(SupportInfoError):
+    def __init__(self, filter_value: str):
+        self.filter_value = filter_value
+        super().__init__(f"Invalid filter: {filter_value}")
+
+
+class OutputWriteError(SupportInfoError):
+    def __init__(self, path: str):
+        self.path = path
+        super().__init__(f"Failed to write output: {path}")
+
+
+class MissingTaskMetadataError(SupportInfoError):
+    def __init__(self, name: str, fields: list[str]):
+        self.name = name
+        self.fields = fields
+        field_list = ",".join(fields)
+        super().__init__(f"Missing task metadata: {name} fields={field_list}")

pyoco/core/models.py

@@ -238,11 +238,10 @@ class Flow:
             # So `flow >> (A | B)` just adds A and B.
             # Then `(A | B) >> C` is handled by Branch.
             pass
-        
-        # Update tail
+
         if new_tasks:
             self._tail = set(new_tasks)
-            
+
         return self
 
     def add_task(self, task: Task):
@@ -284,3 +283,45 @@ class Flow:
             tail_task.dependents.add(task)
             task.dependencies.add(tail_task)
         self._tail = {task}
+
+
+@dataclass
+class TaskIO:
+    name: str
+    type: str
+    required: bool
+    constraints: Optional[List[str]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TaskIO":
+        return cls(
+            name=data.get("name"),
+            type=data.get("type"),
+            required=data.get("required"),
+            constraints=data.get("constraints"),
+        )
+
+
+@dataclass
+class TaskInfo:
+    name: str
+    summary: str
+    inputs: List[TaskIO]
+    outputs: List[TaskIO]
+    origin: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass
+class SupportFilters:
+    name: Optional[List[str]] = None
+    origin: Optional[List[str]] = None
+    tag: Optional[List[str]] = None
+
+
+@dataclass
+class SupportInfo:
+    kind: str
+    format: str
+    content: str
+    filters: SupportFilters

pyoco/discovery/loader.py

@@ -1,6 +1,5 @@
 import importlib
-import pkgutil
-import sys
+import os
 from typing import Dict, List, Any, Set
 from ..core.models import Task
 from ..dsl.syntax import TaskWrapper
@@ -11,30 +10,28 @@ class TaskLoader:
         self.config = config
         self.strict = strict
         self.tasks: Dict[str, Task] = {}
+        self.task_infos: Dict[str, Any] = {}
         self._explicit_tasks: Set[str] = set()
         self.plugin_reports: List[Dict[str, Any]] = []
 
     def load(self):
         # Load explicitly defined tasks in config FIRST (Higher priority)
         for task_name, task_conf in self.config.tasks.items():
-            if task_conf.callable:
-                self._load_explicit_task(task_name, task_conf)
+            callable_path = self._conf_get(task_conf, "callable")
+            if callable_path:
+                self._load_explicit_task(task_name, task_conf, callable_path)
                 self._explicit_tasks.add(task_name)
 
-        # Load from packages
-        for package in self.config.discovery.packages:
-            self._load_package(package)
-        
-        # Load from entry points (simplified)
-        for ep in self.config.discovery.entry_points:
-            self._load_module(ep)
-            
-        # Load from glob modules
-        for pattern in self.config.discovery.glob_modules:
-            self._load_glob_modules(pattern)
+        self._load_env_modules()
 
         self._load_entry_point_plugins()
 
+    def _load_env_modules(self) -> None:
+        raw = os.getenv("PYOCO_DISCOVERY_MODULES", "")
+        modules = [item.strip() for item in raw.replace(",", " ").split() if item.strip()]
+        for module_name in modules:
+            self._load_module(module_name)
+
     def _register_task(self, name: str, task: Task):
         if name in self.tasks:
             if name in self._explicit_tasks:
@@ -51,24 +48,27 @@ class TaskLoader:
         # Apply config overlay if exists
         if self.config and name in self.config.tasks:
             conf = self.config.tasks[name]
-            if not conf.callable:
-                if conf.inputs:
-                    task.inputs.update(conf.inputs)
-                if conf.outputs:
-                    task.outputs.extend(conf.outputs)
+            if not self._conf_get(conf, "callable"):
+                inputs = self._conf_get(conf, "inputs") or {}
+                outputs = self._conf_get(conf, "outputs") or []
+                if inputs:
+                    task.inputs.update(inputs)
+                if outputs:
+                    task.outputs.extend(outputs)
 
         self.tasks[name] = task
 
-    def _load_package(self, package_name: str):
-        try:
-            pkg = importlib.import_module(package_name)
-            if hasattr(pkg, '__path__'):
-                for _, name, _ in pkgutil.iter_modules(pkg.__path__, pkg.__name__ + "."):
-                    self._load_module(name)
+    def _register_task_info(self, info: Any):
+        name = getattr(info, "name", None)
+        if not name:
+            return
+        if name in self.task_infos:
+            msg = f"Task metadata '{name}' already defined."
+            if self.strict:
+                raise ValueError(f"{msg} (Strict mode enabled)")
             else:
-                self._scan_module(pkg)
-        except ImportError as e:
-            print(f"Warning: Could not import package {package_name}: {e}")
+                print(f"Warning: {msg} Overwriting.")
+        self.task_infos[name] = info
 
     def _load_module(self, module_name: str):
         try:
@@ -76,30 +76,6 @@ class TaskLoader:
             self._scan_module(mod)
         except ImportError as e:
             print(f"Warning: Could not import module {module_name}: {e}")
-            
-    def _load_glob_modules(self, pattern: str):
-        import glob
-        import os
-        
-        # Pattern is likely a file path glob, e.g. "jobs/*.py"
-        # We need to convert file paths to module paths
-        files = glob.glob(pattern, recursive=True)
-        for file_path in files:
-            if not file_path.endswith(".py"):
-                continue
-                
-            # Convert path to module
-            # This is tricky without knowing the root. 
-            # Assumption: running from root, and file path is relative to root.
-            # e.g. "myproject/tasks/foo.py" -> "myproject.tasks.foo"
-            
-            rel_path = os.path.relpath(file_path)
-            if rel_path.startswith(".."):
-                # Out of tree, skip or warn
-                continue
-                
-            module_name = rel_path.replace(os.sep, ".")[:-3] # strip .py
-            self._load_module(module_name)
 
     def _load_entry_point_plugins(self):
         entries = iter_entry_points()
@@ -109,6 +85,7 @@ class TaskLoader:
                 "value": ep.value,
                 "module": getattr(ep, "module", ""),
                 "tasks": [],
+                "warnings": [],
             }
             registry = PluginRegistry(self, ep.name)
             try:
@@ -116,7 +93,11 @@ class TaskLoader:
                 if not callable(hook):
                     raise TypeError("Entry point must be callable")
                 hook(registry)
-                info["tasks"] = list(registry.registered_names)
+                info["tasks"] = list(registry.records)
+                info["task_infos"] = list(registry.task_infos.values())
+                info["warnings"] = list(registry.warnings)
+                if not registry.records:
+                    info["warnings"].append("no tasks registered")
             except Exception as exc:
                 info["error"] = str(exc)
                 if self.strict:
@@ -130,13 +111,17 @@ class TaskLoader:
                 self._register_task(name, obj.task)
             elif isinstance(obj, Task):
                 self._register_task(name, obj)
-            elif callable(obj) and getattr(obj, '__pyoco_task__', False):
-                # Convert to Task if not already
-                pass
 
-    def _load_explicit_task(self, name: str, conf: Any):
+    def _conf_get(self, conf: Any, key: str):
+        if hasattr(conf, key):
+            return getattr(conf, key)
+        if isinstance(conf, dict):
+            return conf.get(key)
+        return None
+
+    def _load_explicit_task(self, name: str, conf: Any, callable_path: str):
         # Load callable
-        module_path, func_name = conf.callable.split(':')
+        module_path, func_name = callable_path.split(':')
         try:
             mod = importlib.import_module(module_path)
             obj = getattr(mod, func_name)
@@ -150,8 +135,8 @@ class TaskLoader:
                 
             # Create a Task wrapper
             t = Task(func=real_func, name=name)
-            t.inputs = conf.inputs
-            t.outputs = conf.outputs
+            t.inputs = self._conf_get(conf, "inputs") or {}
+            t.outputs = self._conf_get(conf, "outputs") or []
             self.tasks[name] = t
         except (ImportError, AttributeError) as e:
             print(f"Error loading task {name}: {e}")

pyoco/discovery/plugins.py

@@ -1,12 +1,20 @@
 from __future__ import annotations
 
 from importlib import metadata as importlib_metadata
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Type
 
-from ..core.models import Task
+from ..core.models import Task, TaskInfo, TaskIO
+from ..core.exceptions import MissingTaskMetadataError
 from ..dsl.syntax import TaskWrapper
 
 
+class CallablePluginTask(Task):
+    """Lightweight subclass so callable registrations still appear as Task-derived."""
+
+    def __init__(self, func: Callable, name: str):
+        super().__init__(func=func, name=name)
+
+
 def iter_entry_points(group: str = "pyoco.tasks"):
     eps = importlib_metadata.entry_points()
     if hasattr(eps, "select"):
@@ -32,6 +40,47 @@ class PluginRegistry:
         self.loader = loader
         self.provider_name = provider_name
         self.registered_names: List[str] = []
+        self.records: List[Dict[str, Any]] = []
+        self.warnings: List[str] = []
+        self.task_infos: Dict[str, TaskInfo] = {}
+
+    def task_info(
+        self,
+        *,
+        name: Optional[str] = None,
+        summary: Optional[str] = None,
+        inputs: Optional[List[Any]] = None,
+        outputs: Optional[List[Any]] = None,
+        tags: Optional[List[str]] = None,
+        origin: Optional[str] = None,
+    ) -> None:
+        missing = []
+        if not name:
+            missing.append("name")
+        if not summary:
+            missing.append("summary")
+        if inputs is None:
+            missing.append("inputs")
+        if outputs is None:
+            missing.append("outputs")
+        if missing:
+            raise MissingTaskMetadataError(name or "<unknown>", missing)
+
+        if not isinstance(inputs, list) or not isinstance(outputs, list):
+            raise MissingTaskMetadataError(name, ["inputs", "outputs"])
+        task_inputs = self._normalize_taskio_list(inputs, "inputs", name)
+        task_outputs = self._normalize_taskio_list(outputs, "outputs", name)
+        info = TaskInfo(
+            name=name,
+            summary=summary,
+            inputs=task_inputs,
+            outputs=task_outputs,
+            origin=origin or self.provider_name,
+            tags=tags or [],
+        )
+        self.task_infos[name] = info
+        if hasattr(self.loader, "_register_task_info"):
+            self.loader._register_task_info(info)
 
     def task(
         self,
@@ -70,23 +119,92 @@ class PluginRegistry:
         outputs: Optional[List[str]] = None,
     ) -> Task:
         task_name = name or getattr(func, "__name__", f"{self.provider_name}_task")
-        task = Task(func=func, name=task_name)
+        task = CallablePluginTask(func=func, name=task_name)
         if inputs:
             task.inputs.update(inputs)
         if outputs:
             task.outputs.extend(outputs)
-        self.loader._register_task(task_name, task)
-        self.registered_names.append(task_name)
+        self._finalize_task(task, origin="callable")
+        return task
+
+    def task_class(
+        self,
+        task_cls: Type[Task],
+        *args: Any,
+        name: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Task:
+        if not issubclass(task_cls, Task):
+            raise TypeError(f"{task_cls} is not a Task subclass")
+        task = task_cls(*args, **kwargs)
+        if name:
+            task.name = name
+        self._finalize_task(task, origin="task_class")
         return task
 
     def add(self, obj: Any, *, name: Optional[str] = None) -> None:
         if isinstance(obj, TaskWrapper):
-            self.loader._register_task(name or obj.task.name, obj.task)
-            self.registered_names.append(name or obj.task.name)
+            task = obj.task
+            if name:
+                task.name = name
+            self._finalize_task(task, origin="wrapper")
         elif isinstance(obj, Task):
-            self.loader._register_task(name or obj.name, obj)
-            self.registered_names.append(name or obj.name)
+            if name:
+                obj.name = name
+            origin = "task_class" if obj.__class__ is not Task else "task"
+            self._finalize_task(obj, origin=origin)
         elif callable(obj):
             self.register_callable(obj, name=name)
         else:
             raise TypeError(f"Unsupported task object: {obj!r}")
+
+    def _finalize_task(self, task: Task, origin: str) -> None:
+        warnings = self._validate_task(task, origin)
+        self.loader._register_task(task.name, task)
+        self.registered_names.append(task.name)
+        self.records.append(
+            {
+                "name": task.name,
+                "origin": origin,
+                "class": task.__class__.__name__,
+                "warnings": warnings,
+            }
+        )
+        for msg in warnings:
+            self.warnings.append(f"{task.name}: {msg}")
+
+    def _validate_task(self, task: Task, origin: str) -> List[str]:
+        warnings: List[str] = []
+        if not getattr(task, "name", None):
+            generated = f"{self.provider_name}_{len(self.registered_names) + 1}"
+            task.name = generated
+            warnings.append(f"name missing; auto-assigned '{generated}'")
+        if not callable(getattr(task, "func", None)):
+            warnings.append("task.func is not callable")
+        if origin == "callable":
+            warnings.append("registered via callable; prefer Task subclass for extensibility")
+        if task.__class__ is Task and origin not in ("callable", "wrapper"):
+            warnings.append("plain Task instance detected; subclass Task for metadata support")
+        return warnings
+
+    def _normalize_taskio_list(self, items: List[Any], label: str, task_name: str) -> List[TaskIO]:
+        normalized: List[TaskIO] = []
+        for idx, item in enumerate(items):
+            if isinstance(item, TaskIO):
+                normalized.append(item)
+                continue
+            if isinstance(item, dict):
+                taskio = TaskIO.from_dict(item)
+                missing = []
+                if not taskio.name:
+                    missing.append(f"{label}[{idx}].name")
+                if not taskio.type:
+                    missing.append(f"{label}[{idx}].type")
+                if taskio.required is None:
+                    missing.append(f"{label}[{idx}].required")
+                if missing:
+                    raise MissingTaskMetadataError(task_name, missing)
+                normalized.append(taskio)
+                continue
+            raise MissingTaskMetadataError(task_name, [f"{label}[{idx}]"])
+        return normalized

pyoco/schemas/config.py

@@ -13,12 +13,6 @@ class FlowConfig:
     graph: str
     defaults: Dict[str, Any] = field(default_factory=dict)
 
-@dataclass
-class DiscoveryConfig:
-    entry_points: List[str] = field(default_factory=list)
-    packages: List[str] = field(default_factory=list)
-    glob_modules: List[str] = field(default_factory=list)
-
 @dataclass
 class RuntimeConfig:
     expose_env: List[str] = field(default_factory=list)
@@ -28,23 +22,27 @@ class PyocoConfig:
     version: int
     flows: Dict[str, FlowConfig]
     tasks: Dict[str, TaskConfig]
-    discovery: DiscoveryConfig = field(default_factory=DiscoveryConfig)
     runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
 
     @classmethod
     def from_yaml(cls, path: str) -> 'PyocoConfig':
         with open(path, 'r') as f:
-            data = yaml.safe_load(f)
+            data = yaml.safe_load(f) or {}
         
         # Simple manual parsing/validation for MVP
         # In a real app, use pydantic or similar
         
         flows = {k: FlowConfig(**v) for k, v in data.get('flows', {}).items()}
         tasks = {k: TaskConfig(**v) for k, v in data.get('tasks', {}).items()}
-        
-        disc_data = data.get('discovery', {})
-        discovery = DiscoveryConfig(**disc_data)
-        
+
+        if "discovery" in data:
+            raise ValueError(
+                "Unsupported config key 'discovery'.\n"
+                "For safety, discovery scope is not configurable in flow.yaml.\n"
+                "Remove 'discovery' and use PYOCO_DISCOVERY_MODULES to import extra modules, "
+                "or define tasks explicitly via tasks.<name>.callable."
+            )
+
         run_data = data.get('runtime', {})
         runtime = RuntimeConfig(**run_data)
         
@@ -52,6 +50,5 @@ class PyocoConfig:
             version=data.get('version', 1),
             flows=flows,
             tasks=tasks,
-            discovery=discovery,
             runtime=runtime
         )

pyoco/support/__init__.py

@@ -0,0 +1,21 @@
+from .service import SupportInfoService
+
+
+def build(
+    kind: str,
+    config_path: str,
+    format: str = "prompt",
+    filters=None,
+    output_path: str | None = None,
+):
+    service = SupportInfoService()
+    return service.build(
+        kind=kind,
+        config_path=config_path,
+        format=format,
+        filters=filters,
+        output_path=output_path,
+    )
+
+
+__all__ = ["SupportInfoService", "build"]

pyoco/support/collector.py

@@ -0,0 +1,56 @@
+from typing import List
+
+from ..core.exceptions import MissingTaskMetadataError, TaskNotFoundError
+from ..core.models import SupportFilters, TaskInfo
+from ..discovery.loader import TaskLoader
+from ..schemas.config import PyocoConfig
+from .filters import filters_label, normalize_filters, validate_filters
+
+
+class TaskInfoCollector:
+    def collect(self, config_path: str, filters: SupportFilters | None = None) -> List[TaskInfo]:
+        normalized = normalize_filters(filters)
+        validate_filters(normalized)
+
+        config = PyocoConfig.from_yaml(config_path)
+        loader = TaskLoader(config)
+        loader.load()
+
+        task_names = sorted(loader.tasks.keys())
+        if normalized.name:
+            task_names = [name for name in task_names if name in normalized.name]
+        if not task_names:
+            raise TaskNotFoundError(filters_label(normalized))
+
+        infos: List[TaskInfo] = []
+        missing: List[tuple[str, List[str]]] = []
+        for name in task_names:
+            info = loader.task_infos.get(name)
+            if not info:
+                missing.append((name, ["summary", "inputs", "outputs"]))
+                continue
+            missing_fields: List[str] = []
+            if not info.summary:
+                missing_fields.append("summary")
+            if info.inputs is None:
+                missing_fields.append("inputs")
+            if info.outputs is None:
+                missing_fields.append("outputs")
+            if missing_fields:
+                missing.append((name, missing_fields))
+                continue
+            infos.append(info)
+
+        if missing:
+            name, fields = missing[0]
+            raise MissingTaskMetadataError(name, fields)
+
+        if normalized.origin:
+            infos = [info for info in infos if info.origin in normalized.origin]
+        if normalized.tag:
+            infos = [info for info in infos if info.tags and any(tag in info.tags for tag in normalized.tag)]
+
+        if not infos:
+            raise TaskNotFoundError(filters_label(normalized))
+
+        return infos

pyoco/support/filters.py

@@ -0,0 +1,56 @@
+from typing import Any, Iterable, List
+
+from ..core.exceptions import InvalidFilterError
+from ..core.models import SupportFilters
+
+
+def normalize_filters(filters: Any) -> SupportFilters:
+    if filters is None:
+        return SupportFilters()
+    if isinstance(filters, SupportFilters):
+        return filters
+    if isinstance(filters, dict):
+        allowed = {"name", "origin", "tag"}
+        extra = set(filters.keys()) - allowed
+        if extra:
+            raise InvalidFilterError(",".join(sorted(extra)))
+        return SupportFilters(
+            name=_normalize_list(filters.get("name")),
+            origin=_normalize_list(filters.get("origin")),
+            tag=_normalize_list(filters.get("tag")),
+        )
+    raise InvalidFilterError(str(filters))
+
+
+def validate_filters(filters: SupportFilters) -> None:
+    for label, value in ("name", filters.name), ("origin", filters.origin), ("tag", filters.tag):
+        if value is None:
+            continue
+        if not isinstance(value, list) or not value:
+            raise InvalidFilterError(label)
+        for item in value:
+            if not isinstance(item, str) or not item.strip():
+                raise InvalidFilterError(label)
+
+
+def filters_label(filters: SupportFilters) -> str:
+    parts: List[str] = []
+    if filters.name:
+        parts.append(f"name={','.join(filters.name)}")
+    if filters.origin:
+        parts.append(f"origin={','.join(filters.origin)}")
+    if filters.tag:
+        parts.append(f"tag={','.join(filters.tag)}")
+    if not parts:
+        return "*"
+    return " ".join(parts)
+
+
+def _normalize_list(value: Any) -> List[str] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, Iterable):
+        return list(value)
+    return None

pyoco/support/renderer.py

@@ -0,0 +1,188 @@
+import json
+from typing import Dict, List, Tuple
+
+from ..core.exceptions import InvalidFormatError
+from ..core.models import TaskInfo
+
+
+class SupportInfoRenderer:
+    def render(self, kind: str, tasks: List[TaskInfo] | None, format: str) -> str:
+        if format not in ("prompt", "json", "md"):
+            raise InvalidFormatError(format)
+        if kind == "guide":
+            return self._render_guide(format)
+        if kind not in ("tasks", "task"):
+            raise ValueError(f"Unknown support kind: {kind}")
+        return self._render_tasks(kind, tasks or [], format)
+
+    def _render_tasks(self, kind: str, tasks: List[TaskInfo], format: str) -> str:
+        groups = self._group_tasks(tasks)
+        if format == "json":
+            payload = {
+                "kind": kind,
+                "groups": [
+                    {
+                        "origin": origin,
+                        "tasks": [self._task_to_dict(t) for t in items],
+                    }
+                    for origin, items in groups
+                ],
+            }
+            return json.dumps(payload, indent=2)
+        if format == "md":
+            return self._render_tasks_md(kind, groups)
+        return self._render_tasks_prompt(kind, groups)
+
+    def _render_tasks_prompt(self, kind: str, groups: List[Tuple[str, List[TaskInfo]]]) -> str:
+        lines = [f"Pyoco support ({kind})", ""]
+        for origin, items in groups:
+            lines.append(f"Origin: {origin}")
+            for task in items:
+                lines.append(f"- name: {task.name}")
+                lines.append(f"  summary: {task.summary}")
+                lines.append("  inputs:")
+                for io in task.inputs:
+                    lines.append(
+                        f"    - {io.name} ({io.type}, required={io.required})"
+                    )
+                lines.append("  outputs:")
+                for io in task.outputs:
+                    lines.append(
+                        f"    - {io.name} ({io.type}, required={io.required})"
+                    )
+                if task.tags:
+                    lines.append(f"  tags: {', '.join(task.tags)}")
+            lines.append("")
+        return "\n".join(lines).rstrip()
+
+    def _render_tasks_md(self, kind: str, groups: List[Tuple[str, List[TaskInfo]]]) -> str:
+        lines = [f"# Pyoco support ({kind})", ""]
+        for origin, items in groups:
+            lines.append(f"## Origin: {origin}")
+            for task in items:
+                lines.append(f"### {task.name}")
+                lines.append(task.summary)
+                lines.append("")
+                lines.append("**Inputs**")
+                lines.append("")
+                if task.inputs:
+                    lines.append("| name | type | required | constraints |")
+                    lines.append("|---|---|---|---|")
+                    for io in task.inputs:
+                        constraints = ", ".join(io.constraints) if io.constraints else ""
+                        lines.append(
+                            f"| {io.name} | {io.type} | {io.required} | {constraints} |"
+                        )
+                else:
+                    lines.append("none")
+                lines.append("")
+                lines.append("**Outputs**")
+                lines.append("")
+                if task.outputs:
+                    lines.append("| name | type | required | constraints |")
+                    lines.append("|---|---|---|---|")
+                    for io in task.outputs:
+                        constraints = ", ".join(io.constraints) if io.constraints else ""
+                        lines.append(
+                            f"| {io.name} | {io.type} | {io.required} | {constraints} |"
+                        )
+                else:
+                    lines.append("none")
+                if task.tags:
+                    lines.append("")
+                    lines.append(f"**Tags**: {', '.join(task.tags)}")
+                lines.append("")
+        return "\n".join(lines).rstrip()
+
+    def _task_to_dict(self, task: TaskInfo) -> Dict[str, object]:
+        return {
+            "name": task.name,
+            "summary": task.summary,
+            "inputs": [self._taskio_to_dict(io) for io in task.inputs],
+            "outputs": [self._taskio_to_dict(io) for io in task.outputs],
+            "origin": task.origin,
+            "tags": task.tags or [],
+        }
+
+    def _taskio_to_dict(self, io) -> Dict[str, object]:
+        return {
+            "name": io.name,
+            "type": io.type,
+            "required": io.required,
+            "constraints": io.constraints or [],
+        }
+
+    def _render_guide(self, format: str) -> str:
+        guide = self._guide_payload()
+        if format == "json":
+            return json.dumps({"kind": "guide", **guide}, indent=2)
+        if format == "md":
+            return self._render_guide_md(guide)
+        return self._render_guide_prompt(guide)
+
+    def _guide_payload(self) -> Dict[str, str]:
+        template = (
+            "version: 1\n"
+            "flows:\n"
+            "  main:\n"
+            "    graph: \"task_a >> task_b\"\n"
+            "    defaults:\n"
+            "      seed: \"bar\"\n"
+            "tasks:\n"
+            "  task_a:\n"
+            "    callable: \"pkg.module:task_a\"\n"
+            "    inputs:\n"
+            "      x: \"$ctx.params.seed\"\n"
+    "    outputs:\n"
+            "      - \"params.shared\"\n"
+            "  task_b:\n"
+            "    callable: \"pkg.module:task_b\"\n"
+            "    inputs:\n"
+            "      input_a: \"$ctx.params.shared\"\n"
+        )
+        graph = (
+            "- Use >> to define dependencies: A >> B means B depends on A.\n"
+            "- Use | to define OR branches: (A | B) >> C means C waits for any.\n"
+            "- Wrap with flow variable in graph string (exec/eval).\n"
+        )
+        inputs = (
+            "- Prefer $ctx.params.<key> to connect tasks via shared params.\n"
+            "- If values would be overwritten or you need an explicit upstream output, use $node.<task_name>.output.\n"
+            "- Use $env.<KEY> to reference allowed environment variables.\n"
+            "- Task discovery is not configured in flow.yaml. Use explicit tasks.callable, entry-point plugins (group 'pyoco.tasks'),\n"
+            "  or set PYOCO_DISCOVERY_MODULES to import extra modules. The 'discovery' config key is not supported.\n"
+        )
+        return {"template": template, "graph_syntax": graph, "input_refs": inputs}
+
+    def _render_guide_prompt(self, guide: Dict[str, str]) -> str:
+        return (
+            "Pyoco flow.yaml guide\n\n"
+            "Template:\n"
+            f"{guide['template']}\n"
+            "Graph syntax:\n"
+            f"{guide['graph_syntax']}\n"
+            "Input references:\n"
+            f"{guide['input_refs']}"
+        ).rstrip()
+
+    def _render_guide_md(self, guide: Dict[str, str]) -> str:
+        return (
+            "# Pyoco flow.yaml guide\n\n"
+            "## Template\n\n"
+            "```yaml\n"
+            f"{guide['template']}"
+            "```\n\n"
+            "## Graph syntax\n\n"
+            f"{guide['graph_syntax']}\n"
+            "## Input references\n\n"
+            f"{guide['input_refs']}"
+        ).rstrip()
+
+    def _group_tasks(self, tasks: List[TaskInfo]) -> List[Tuple[str, List[TaskInfo]]]:
+        groups: Dict[str, List[TaskInfo]] = {}
+        for task in tasks:
+            origin = task.origin or "unknown"
+            groups.setdefault(origin, []).append(task)
+        for items in groups.values():
+            items.sort(key=lambda t: t.name)
+        return [(origin, groups[origin]) for origin in sorted(groups.keys())]

pyoco/support/service.py

@@ -0,0 +1,42 @@
+from ..core.exceptions import InvalidFilterError
+from ..core.models import SupportFilters
+from .collector import TaskInfoCollector
+from .filters import normalize_filters, validate_filters
+from .renderer import SupportInfoRenderer
+from .writer import SupportInfoWriter
+
+
+class SupportInfoService:
+    def __init__(
+        self,
+        collector: TaskInfoCollector | None = None,
+        renderer: SupportInfoRenderer | None = None,
+        writer: SupportInfoWriter | None = None,
+    ) -> None:
+        self.collector = collector or TaskInfoCollector()
+        self.renderer = renderer or SupportInfoRenderer()
+        self.writer = writer or SupportInfoWriter()
+
+    def build(
+        self,
+        *,
+        kind: str,
+        config_path: str,
+        format: str = "prompt",
+        filters: SupportFilters | None = None,
+        output_path: str | None = None,
+    ) -> str:
+        normalized = normalize_filters(filters)
+        validate_filters(normalized)
+
+        if kind == "task" and not normalized.name:
+            raise InvalidFilterError("name")
+
+        tasks = []
+        if kind in ("tasks", "task"):
+            tasks = self.collector.collect(config_path, normalized)
+
+        content = self.renderer.render(kind, tasks, format)
+        if output_path:
+            self.writer.write(content, output_path)
+        return content

pyoco/support/writer.py

@@ -0,0 +1,15 @@
+import os
+
+from ..core.exceptions import OutputWriteError
+
+
+class SupportInfoWriter:
+    def write(self, content: str, output_path: str) -> None:
+        try:
+            parent = os.path.dirname(output_path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(content)
+        except Exception as exc:
+            raise OutputWriteError(output_path) from exc

{pyoco-0.5.0.dist-info → pyoco-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoco
-Version: 0.5.0
+Version: 0.6.0
 Summary: A workflow engine with sugar syntax
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -133,22 +133,29 @@ Or via CLI flag:
 pyoco run --non-cute ...
 ```
 
-## 🔭 Observability Bridge (v0.5)
+## 🔭 Observability / Server (Archived)
 
-- `/metrics` exposes Prometheus counters (`pyoco_runs_total`, `pyoco_runs_in_progress`) and histograms (`pyoco_task_duration_seconds`, `pyoco_run_duration_seconds`). Point Grafana/Prometheus at it to watch pipelines without opening sockets.
-- `/runs` now accepts `status`, `flow`, `limit` query params; `/runs/{id}/logs?tail=100` fetches only the latest snippets for dashboards.
-- Webhook notifications fire when runs COMPLETE/FAIL—configure via `PYOCO_WEBHOOK_*` env vars and forward to Slack or your alerting stack.
-- Import `docs/grafana_pyoco_cute.json` for a lavender/orange starter dashboard (3 panels: in-progress count, completion trend, per-flow latency).
-- 詳細な手順は [docs/observability.md](docs/observability.md) を参照してください。
+Observability and server-related docs are archived and out of scope for the current requirements.  
+See `docs/archive/observability.md` and `docs/archive/roadmap.md`.
 
 ## 🧩 Plug-ins
 
-Need to share domain-specific tasks? Publish an entry point under `pyoco.tasks` and pyoco will auto-load it. See [docs/plugins.md](docs/plugins.md) for the `PluginRegistry` decorator, example `pyproject.toml`, and `pyoco plugins list` CLI helper.
+Need to share domain-specific tasks? Publish an entry point under `pyoco.tasks` and pyoco will auto-load it. We recommend **Task subclasses first** (callables still work with warnings). See [docs/plugins.md](docs/plugins.md) for examples, quickstart, and `pyoco plugins list` / `pyoco plugins lint`.
+
+**Big data note:** pass handles, not copies. For large tensors/images, stash paths or handles in `ctx.artifacts`/`ctx.scratch` and let downstream tasks materialize only when needed. For lazy pipelines (e.g., DataPipe), log the pipeline when you actually iterate (typically the training task) instead of materializing upstream.
+
+## 🧭 Task Discovery (Security)
+
+Pyoco does not allow configuring discovery scope in `flow.yaml` (the `discovery:` key is rejected) to reduce the risk of importing unexpected code.
+
+- **Entry point plug-ins**: auto-loaded from `importlib.metadata.entry_points(group="pyoco.tasks")`
+- **Extra imports (ops-controlled)**: set `PYOCO_DISCOVERY_MODULES` (comma/space-separated module names), e.g. `PYOCO_DISCOVERY_MODULES=tasks,myapp.extra_tasks`
+- **Explicit tasks**: prefer `tasks.<name>.callable` in `flow.yaml` (see tutorials)
 
 ## 📚 Documentation
 
 - [Tutorials](docs/tutorial/index.md)
-- [Roadmap](docs/roadmap.md)
+- [Roadmap (Archived)](docs/archive/roadmap.md)
 
 ## 💖 Contributing
 

{pyoco-0.5.0.dist-info → pyoco-0.6.0.dist-info}/RECORD

@@ -1,33 +1,39 @@
-pyoco/__init__.py,sha256=E2pgDGvGRSVon7dSqIM4UD55LgVpf4jiZZA-70kOcuw,409
+pyoco/__init__.py,sha256=PJIk0A3NCknNtp7hiC-Q4xpTmpVQ_AD2KbrQLcOT_1s,442
 pyoco/client.py,sha256=Y95NmMsOKTJ9AZJEg_OzHamC_w32YWmSVS653mpqHVQ,3141
 pyoco/socketless_reset.py,sha256=KsAF4I23_Kbhy9fIWFARzV5QaIOQqbl0U0yPb8a34sM,129
 pyoco/cli/entry.py,sha256=zPIG0Gx-cFO8Cf1Z3wD3Ifz_2sHaryHZ6mCRri2WEqE,93
-pyoco/cli/main.py,sha256=W3U-T4SliJHy4wZ70QoN2c9Mep--XxlEa8YkHe9DLuU,16515
+pyoco/cli/main.py,sha256=-sVxldl1fOVedf2KUs2aCbzIQNPgXuRTrr_t5Pbavyo,22126
 pyoco/core/base_task.py,sha256=z7hOFntAPv4yCADapS-fhtLe5eWqaO8k3T1r05YEEUE,2106
 pyoco/core/context.py,sha256=TeCUriOmg7qZB3nMRu8HPdPshMW6pMVx48xZLY6a-A4,6524
 pyoco/core/engine.py,sha256=iX2Id8ryFt-xeZgraqnF3uqkI6ubiZt5NBNYWX6Qv1s,24166
-pyoco/core/exceptions.py,sha256=G82KY8PCnAhp3IDDIG8--Uh3EfVa192zei3l6ihfShI,565
-pyoco/core/models.py,sha256=8faYURF43-7IebqzTIorHxpCeC4TZfoXWjGyPNaWhyI,10501
-pyoco/discovery/loader.py,sha256=vC729i1bR358u6YwiVX2uonZ80WxjFGFqJRlhX89Sf0,5942
-pyoco/discovery/plugins.py,sha256=pNMWxS03jWPuUV2tApGch2VL40EyKLOOeYT-OPBBBRQ,2806
+pyoco/core/exceptions.py,sha256=gQbaGMJIlyidqQYj_NEFj-lxQmDtlfj659d_uLEBVY8,1606
+pyoco/core/models.py,sha256=Abuu2UX5SsXXjJKopxDsbQCIAdW82GbdnptsK1N4l3A,11280
+pyoco/discovery/loader.py,sha256=SjFZ0joo4qLQf8pHPrSfn4kI0Ip30G_N9ia8BJzuDUM,5470
+pyoco/discovery/plugins.py,sha256=st95xmOiDNXtpq7fIl5_wqvvDfXIJU5fNtUeTi7vRJM,7302
 pyoco/dsl/__init__.py,sha256=xWdb60pSRL8lNFk4GHF3EJ4hon0uiWqpv264g6-4gdg,45
 pyoco/dsl/expressions.py,sha256=BtEIxPSf3BU-wPNEicIqX_TVZ4fAnlWGrzrrfc6pU1g,4875
 pyoco/dsl/nodes.py,sha256=qDiIEsAJHnD8dpuOd-Rpy6OORCW6KDW_BdYiA2BKu18,1041
 pyoco/dsl/syntax.py,sha256=kYP5uGbwxmkSd_zeSksax8iWm_7UlRW5JxE9_DoSqbk,8638
 pyoco/dsl/validator.py,sha256=HXjcc-GzjH72YByaNxAg_7YOZsVsFDFnUaenVwd5PbY,3576
-pyoco/schemas/config.py,sha256=KkGZK3GxTHoIHEGb4f4k8GE2W-aBN4iPzmc_HrwuROU,1735
+pyoco/schemas/config.py,sha256=LBCGRSPtacd4a10EXXkk7wAL4k-d-zKPam-pIaYbmJE,1701
 pyoco/server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyoco/server/api.py,sha256=vu2ieDZgHbi8cysO2rS-lcxqWiSQprIcqRn6GkwTtKo,3890
 pyoco/server/metrics.py,sha256=92sHZKka_yBNBGlHZgRIteywx97aoTa-MnXh3UJ0HJY,2952
 pyoco/server/models.py,sha256=ir5AuvyXQigmaynA7bS_0RNJcJo2VtpJl0GjRZrj2rU,786
 pyoco/server/store.py,sha256=ITYAV1QlPWDnceywqjjJZW9E0CyocFlPmqqfjcoM-wA,9133
 pyoco/server/webhook.py,sha256=fBSLWTDN7sIWSK0AUVuiCSdVVBFV_AyP-XEKOcdMXmQ,3643
+pyoco/support/__init__.py,sha256=MofLlxywBorHrzOgAcs5cFTSAokNcPDVyQi2sr8WPdM,419
+pyoco/support/collector.py,sha256=jeT7A9fMhxmx0D9aqAqWiWYdaSqxkrvUIX-KgVVLJto,2074
+pyoco/support/filters.py,sha256=7TGkB8MNjfLm45kwXfD90jJ1N3GzTVt_jo6paeEEzBM,1805
+pyoco/support/renderer.py,sha256=vFrOW10SSjE-WMqgGj7gci28jv-NXHjBocB1E_luQxA,7685
+pyoco/support/service.py,sha256=qMi9zUrQ43dsuk98_Vu9_xu4E7ll8pTiSxNQp320eho,1352
+pyoco/support/writer.py,sha256=FmRo2XWlwKzCcJ3StRiAnKC4OsOSSls-raCDwKYpXlo,470
 pyoco/trace/backend.py,sha256=a1css94_lhO4SGSPHZ1f59HJqFQtZ5Sjx09Kw7v5bsk,617
 pyoco/trace/console.py,sha256=I-BcF405OGLWoacJWeke8vTT9M5JxSBpJL-NazVyxb4,1742
 pyoco/worker/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyoco/worker/client.py,sha256=862KccXRtfG7zd9ZSLqrpVSV6ev8zeuEHHdtAfLghiM,1557
 pyoco/worker/runner.py,sha256=hyKn5NbuIuF-109CnQbYc8laKbWmwe9ChaLrNUtsVIg,6367
-pyoco-0.5.0.dist-info/METADATA,sha256=SEow4x2y_O6SqeVuEU-_7dT12F-XA24sYVD_hMV6TQM,5251
-pyoco-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyoco-0.5.0.dist-info/top_level.txt,sha256=2JRVocfaWRbX1VJ3zq1c5wQaOK6fMARS6ptVFWyvRF4,6
-pyoco-0.5.0.dist-info/RECORD,,
+pyoco-0.6.0.dist-info/METADATA,sha256=qDs09R2M5X9kSVKokOQsjJ8TES_Cfzl3nGWCglgMN4o,5588
+pyoco-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pyoco-0.6.0.dist-info/top_level.txt,sha256=2JRVocfaWRbX1VJ3zq1c5wQaOK6fMARS6ptVFWyvRF4,6
+pyoco-0.6.0.dist-info/RECORD,,

{pyoco-0.5.0.dist-info → pyoco-0.6.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any