plato-sdk-v2 2.0.64__py3-none-any.whl → 2.3.4__py3-none-any.whl

plato/sims/cli.py

@@ -241,9 +241,11 @@ def _get_function_info(
         }
 
         # Extract parameters
+        params_list = result["params"]
+        assert isinstance(params_list, list)  # type narrowing for ty
         for param_name, param in sig.parameters.items():
             if param_name == "client":
-                result["params"].append("client.httpx")
+                params_list.append("client.httpx")
                 continue
 
             # Get type from hints or annotation
@@ -251,10 +253,10 @@ def _get_function_info(
             type_str = _format_type_annotation(param_type)
 
             if param.default is inspect.Parameter.empty:
-                result["params"].append(f"{param_name}: {type_str}")
+                params_list.append(f"{param_name}: {type_str}")
             else:
                 default_repr = repr(param.default) if param.default is not None else "None"
-                result["params"].append(f"{param_name}: {type_str} = {default_repr}")
+                params_list.append(f"{param_name}: {type_str} = {default_repr}")
 
             # Check if this is the body parameter
             if param_name == "body" and param_type is not inspect.Parameter.empty:
@@ -725,7 +727,7 @@ def _format_response_structure(
     return lines
 
 
-def cmd_info(sim_name: str) -> None:
+def cmd_info(sim_name: str, job_id: str | None = None) -> None:
     """Show detailed information about a sim."""
     try:
         info = registry.get_sim_info(sim_name)
@@ -750,6 +752,15 @@ def cmd_info(sim_name: str) -> None:
     except ImportError:
         pass
 
+    # Handle instruction-based sims differently
+    if info.sim_type == "instruction":
+        _cmd_info_instruction(info, job_id)
+    else:
+        _cmd_info_api(info)
+
+
+def _cmd_info_api(info) -> None:
+    """Show info for API-based sim."""
     if info.auth:
         print(f"Auth Type: {info.auth.type}")
 
@@ -768,6 +779,71 @@ def cmd_info(sim_name: str) -> None:
     print(f"  client = await {info.name}.AsyncClient.create({base_url_example})")
 
 
+def _cmd_info_instruction(info, job_id: str | None) -> None:
+    """Show info for instruction-based sim."""
+    print("Type: Instruction-based (no API client)")
+    print()
+
+    # Show available services
+    if info.services:
+        print("Services:")
+        for name, svc in info.services.items():
+            port = svc.get("port", "?")
+            desc = svc.get("description", "")
+            if job_id:
+                url = f"https://{job_id}--{port}.connect.plato.so"
+                print(f"  {name}: {url}")
+                if desc:
+                    print(f"         {desc}")
+            else:
+                print(f"  {name}: port {port}")
+                if desc:
+                    print(f"         {desc}")
+        print()
+
+    # Show env vars
+    if info.env_vars:
+        print("Environment Variables:")
+        for name, var_config in info.env_vars.items():
+            desc = var_config.get("description", "")
+            if "template" in var_config:
+                print(f"  {name}: (from service URL)")
+            elif "default" in var_config:
+                print(f"  {name}={var_config['default']}")
+            else:
+                print(f"  {name}")
+            if desc:
+                print(f"         {desc}")
+        print()
+
+    # Show instructions
+    if info.instructions:
+        instructions = info.instructions
+        if job_id and info.services:
+            # Build service URLs from job_id and replace placeholders
+            for svc_name, svc_config in info.services.items():
+                port = svc_config.get("port", 80)
+                svc_url = f"https://{job_id}--{port}.connect.plato.so"
+                instructions = instructions.replace(f"{{service:{svc_name}}}", svc_url)
+
+        print("Instructions:")
+        print(instructions)
+        print()
+
+    # Show usage
+    print("Usage:")
+    print(f"  from plato.sims import {info.name}")
+    print()
+    print("  # Get service URLs from job ID")
+    print(f"  service_urls = {info.name}.get_service_urls(job_id)")
+    print()
+    print("  # Get formatted instructions")
+    print(f"  instructions = {info.name}.get_instructions(service_urls)")
+    print()
+    print("  # Get environment variables to set")
+    print(f"  env_vars = {info.name}.get_env_vars(service_urls)")
+
+
 def cmd_endpoints(
     sim_name: str,
     spec_name: str | None = None,
@@ -950,144 +1026,204 @@ def cmd_publish(
         pkg_dir = build_dir / "src" / "plato" / "sims" / service_name
         pkg_dir.mkdir(parents=True)
 
-        # Find OpenAPI spec
         config_dir = config_file.parent
-        spec_file = None
 
-        # Priority 1: specs_dir (new format)
+        # Check for instruction-based sim first
+        instructions_file = None
         if specs_dir:
-            specs_path = config_dir / specs_dir
-            for candidate in ["openapi.json", "openapi.yaml", "openapi.yml"]:
-                candidate_path = specs_path / candidate
-                if candidate_path.exists():
-                    spec_file = candidate_path
-                    break
-        # Priority 2: spec_path (legacy format)
-        elif spec_path:
-            spec_file = config_dir / spec_path
-        # Priority 3: Try common locations in root
-        else:
-            for candidate in ["openapi.yaml", "openapi.yml", "openapi.json", "spec.yaml", "spec.json"]:
-                candidate_path = config_dir / candidate
-                if candidate_path.exists():
-                    spec_file = candidate_path
-                    break
+            instructions_path = config_dir / specs_dir / "instructions.yaml"
+            if instructions_path.exists():
+                instructions_file = instructions_path
+        if not instructions_file:
+            instructions_path = config_dir / "instructions.yaml"
+            if instructions_path.exists():
+                instructions_file = instructions_path
+
+        if instructions_file:
+            # Generate instruction-based SDK
+            print(f"Using instructions config: {instructions_file}")
+            print("Generating instruction-based SDK...")
+            try:
+                import plato
+                from plato._sims_generator import InstructionConfig, InstructionGenerator
 
-        if not spec_file or not spec_file.exists():
-            print(
-                "Error: OpenAPI spec not found. Set 'sdk.specs_dir' or 'sdk.spec_path' in plato-config.yml",
-                file=sys.stderr,
-            )
-            sys.exit(1)
+                generator_version = getattr(plato, "__version__", None)
+                print(f"  Generator version: {generator_version}")
 
-        print(f"Using OpenAPI spec: {spec_file}")
+                instruction_config = InstructionConfig.from_yaml(instructions_file)
+                # Override version from plato-config.yml if set
+                instruction_config.version = version
+
+                generator = InstructionGenerator(
+                    config=instruction_config,
+                    output_path=pkg_dir,
+                    package_name=service_name,
+                    generator_version=generator_version,
+                )
+                generator.generate()
+                print(f"  Generated instruction-based SDK to: {pkg_dir}")
+
+            except ImportError as e:
+                print(f"Error: Missing dependency for SDK generation: {e}", file=sys.stderr)
+                print("Install with: uv add plato-sdk-v2", file=sys.stderr)
+                sys.exit(1)
+            except Exception as e:
+                print(f"Error generating instruction SDK: {e}", file=sys.stderr)
+                sys.exit(1)
 
-        # Load auth config if provided
-        auth_yaml = None
-        if auth_config_path:
-            auth_file = config_dir / auth_config_path
-            if auth_file.exists():
-                auth_yaml = auth_file
         else:
-            # Try specs_dir first, then root
-            search_dirs = []
-            if specs_dir:
-                search_dirs.append(config_dir / specs_dir)
-            search_dirs.append(config_dir)
+            # Generate OpenAPI-based SDK
+            # Find OpenAPI spec
+            spec_file = None
 
-            for search_dir in search_dirs:
-                for candidate in ["auth.yaml", "auth.yml"]:
-                    candidate_path = search_dir / candidate
+            # Priority 1: specs_dir (new format)
+            if specs_dir:
+                specs_path = config_dir / specs_dir
+                for candidate in ["openapi.json", "openapi.yaml", "openapi.yml"]:
+                    candidate_path = specs_path / candidate
                     if candidate_path.exists():
-                        auth_yaml = candidate_path
+                        spec_file = candidate_path
+                        break
+            # Priority 2: spec_path (legacy format)
+            elif spec_path:
+                spec_file = config_dir / spec_path
+            # Priority 3: Try common locations in root
+            else:
+                for candidate in ["openapi.yaml", "openapi.yml", "openapi.json", "spec.yaml", "spec.json"]:
+                    candidate_path = config_dir / candidate
+                    if candidate_path.exists():
+                        spec_file = candidate_path
                         break
-                if auth_yaml:
-                    break
-
-        # Generate SDK code
-        print("Generating SDK code...")
-        try:
-            import plato
-            from plato._sims_generator import AuthConfig, PythonGenerator, parse_openapi
 
-            # Get current plato-sdk-v2 version
-            generator_version = getattr(plato, "__version__", None)
-            print(f"  Generator version: {generator_version}")
+            if not spec_file or not spec_file.exists():
+                print(
+                    "Error: OpenAPI spec or instructions.yaml not found. "
+                    "Set 'sdk.specs_dir' or 'sdk.spec_path' in plato-config.yml",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
 
-            # Check if .generator-version exists and matches
-            if specs_dir:
-                generator_version_file = config_dir / specs_dir / ".generator-version"
-                if generator_version_file.exists():
-                    expected_version = generator_version_file.read_text().strip()
-                    if expected_version and generator_version and expected_version != generator_version:
-                        print(
-                            f"Error: Generator version mismatch. "
-                            f"Expected {expected_version} (from .generator-version), "
-                            f"but running {generator_version}",
-                            file=sys.stderr,
-                        )
-                        print(
-                            f"  Run: uvx --from 'plato-sdk-v2=={expected_version}' plato sims publish",
-                            file=sys.stderr,
-                        )
-                        print(
-                            f"  Or update .generator-version to {generator_version} to use current version",
-                            file=sys.stderr,
-                        )
-                        sys.exit(1)
-
-                # Write/update .generator-version to specs dir
-                if generator_version:
-                    generator_version_file.write_text(f"{generator_version}\n")
-                    print(f"  Updated {generator_version_file}")
-
-            # Load spec
-            with open(spec_file) as f:
-                if spec_file.suffix == ".json":
-                    spec = json.load(f)
-                else:
-                    spec = yaml.safe_load(f)
+            print(f"Using OpenAPI spec: {spec_file}")
 
-            # Load auth config
-            if auth_yaml and auth_yaml.exists():
-                auth = AuthConfig.from_yaml(auth_yaml)
+            # Load auth config if provided
+            auth_yaml = None
+            if auth_config_path:
+                auth_file = config_dir / auth_config_path
+                if auth_file.exists():
+                    auth_yaml = auth_file
             else:
-                # Default auth config
-                auth = AuthConfig(
-                    type="basic",
-                    env_prefix=service_name.upper(),
-                )
+                # Try specs_dir first, then root
+                search_dirs = []
+                if specs_dir:
+                    search_dirs.append(config_dir / specs_dir)
+                search_dirs.append(config_dir)
+
+                for search_dir in search_dirs:
+                    for candidate in ["auth.yaml", "auth.yml"]:
+                        candidate_path = search_dir / candidate
+                        if candidate_path.exists():
+                            auth_yaml = candidate_path
+                            break
+                    if auth_yaml:
+                        break
 
-            # Parse and generate
-            api = parse_openapi(spec)
-            print(f"  Parsed {len(api.endpoints)} endpoints")
-
-            generator = PythonGenerator(
-                api=api,
-                output_path=pkg_dir,
-                spec=spec,
-                package_name=service_name,
-                auth_config=auth,
-                generator_version=generator_version,
-            )
-            generator.generate()
-            print(f"  Generated to: {pkg_dir}")
+            # Generate SDK code
+            print("Generating SDK code...")
+            try:
+                import plato
+                from plato._sims_generator import AuthConfig, PythonGenerator, parse_openapi
+
+                # Get current plato-sdk-v2 version
+                generator_version = getattr(plato, "__version__", None)
+                print(f"  Generator version: {generator_version}")
+
+                # Check if .generator-version exists and matches
+                if specs_dir:
+                    generator_version_file = config_dir / specs_dir / ".generator-version"
+                    if generator_version_file.exists():
+                        expected_version = generator_version_file.read_text().strip()
+                        if expected_version and generator_version and expected_version != generator_version:
+                            print(
+                                f"Error: Generator version mismatch. "
+                                f"Expected {expected_version} (from .generator-version), "
+                                f"but running {generator_version}",
+                                file=sys.stderr,
+                            )
+                            print(
+                                f"  Run: uvx --from 'plato-sdk-v2=={expected_version}' plato sims publish",
+                                file=sys.stderr,
+                            )
+                            print(
+                                f"  Or update .generator-version to {generator_version} to use current version",
+                                file=sys.stderr,
+                            )
+                            sys.exit(1)
+
+                    # Write/update .generator-version to specs dir
+                    if generator_version:
+                        generator_version_file.write_text(f"{generator_version}\n")
+                        print(f"  Updated {generator_version_file}")
+
+                # Load spec (spec_file is guaranteed non-None after check above)
+                assert spec_file is not None
+                with open(spec_file) as f:
+                    if spec_file.suffix == ".json":
+                        spec = json.load(f)
+                    else:
+                        spec = yaml.safe_load(f)
+
+                # Load auth config
+                if auth_yaml and auth_yaml.exists():
+                    auth = AuthConfig.from_yaml(auth_yaml)
+                else:
+                    # Default auth config
+                    auth = AuthConfig(
+                        type="basic",
+                        env_prefix=service_name.upper(),
+                    )
+
+                # Parse and generate
+                api = parse_openapi(spec)
+                print(f"  Parsed {len(api.endpoints)} endpoints")
+
+                generator = PythonGenerator(
+                    api=api,
+                    output_path=pkg_dir,
+                    spec=spec,
+                    package_name=service_name,
+                    auth_config=auth,
+                    generator_version=generator_version,
+                )
+                generator.generate()
+                print(f"  Generated to: {pkg_dir}")
 
-        except ImportError as e:
-            print(f"Error: Missing dependency for SDK generation: {e}", file=sys.stderr)
-            print("Install with: uv add plato-sdk-v2", file=sys.stderr)
-            sys.exit(1)
-        except Exception as e:
-            print(f"Error generating SDK: {e}", file=sys.stderr)
-            sys.exit(1)
+            except ImportError as e:
+                print(f"Error: Missing dependency for SDK generation: {e}", file=sys.stderr)
+                print("Install with: uv add plato-sdk-v2", file=sys.stderr)
+                sys.exit(1)
+            except Exception as e:
+                print(f"Error generating SDK: {e}", file=sys.stderr)
+                sys.exit(1)
 
         # Create pyproject.toml with namespace package structure
+        # Instruction sims need pyyaml; API sims need httpx and pydantic
+        if instructions_file:
+            dependencies = '["pyyaml>=6.0.0"]'
+            # Include yaml file in package data
+            extra_config = f"""
+[tool.hatch.build.targets.wheel.force-include]
+"src/plato/sims/{service_name}/instructions.yaml" = "plato/sims/{service_name}/instructions.yaml"
+"""
+        else:
+            dependencies = '["httpx>=0.25.0", "pydantic>=2.0.0"]'
+            extra_config = ""
+
         pyproject_content = f'''[project]
 name = "{package_name}"
 version = "{version}"
 description = "{description}"
 requires-python = ">=3.10"
-dependencies = ["httpx>=0.25.0", "pydantic>=2.0.0"]
+dependencies = {dependencies}
 
 [build-system]
 requires = ["hatchling"]
@@ -1095,11 +1231,38 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/plato"]
-'''
+{extra_config}'''
         (build_dir / "pyproject.toml").write_text(pyproject_content)
 
         # Create README
-        readme_content = f"""# {package_name}
+        if instructions_file:
+            readme_content = f"""# {package_name}
+
+Auto-generated instruction-based SDK for the {service_name} simulator.
+
+## Installation
+
+```bash
+uv add {package_name} --index-url https://plato.so/api/v2/pypi/{repo}/simple/
+```
+
+## Usage
+
+```python
+from plato.sims.{service_name} import get_instructions, get_service_urls, setup_env
+
+# Get service URLs from job ID
+service_urls = get_service_urls(job_id)
+
+# Get formatted instructions
+instructions = get_instructions(service_urls)
+
+# Set up environment variables
+setup_env(service_urls)
+```
+"""
+        else:
+            readme_content = f"""# {package_name}
 
 Auto-generated SDK for the {service_name} simulator.
 
@@ -1228,9 +1391,22 @@ def main(args: list[str] | None = None) -> None:
     elif command == "info":
         if len(args) < 2:
             print("Error: sim name required", file=sys.stderr)
-            print("Usage: plato sims info <sim_name>", file=sys.stderr)
+            print("Usage: plato sims info <sim_name> [--job-id JOB_ID]", file=sys.stderr)
             sys.exit(1)
-        cmd_info(args[1])
+
+        sim_name = args[1]
+        job_id = None
+
+        # Parse optional --job-id flag
+        i = 2
+        while i < len(args):
+            if args[i] == "--job-id" and i + 1 < len(args):
+                job_id = args[i + 1]
+                i += 2
+            else:
+                i += 1
+
+        cmd_info(sim_name, job_id)
 
     elif command == "endpoints":
         if len(args) < 2:

plato/sims/registry.py

@@ -38,6 +38,11 @@ class SimInfo:
     description: str | None
     auth: AuthRequirement | None
     base_url_suffix: str | None  # e.g., "/api/v1" for EspoCRM
+    # New fields for instruction-based sims
+    sim_type: str = "api"  # "api" or "instruction"
+    services: dict[str, dict[str, Any]] | None = None  # {"main": {"port": 4566, "description": "..."}}
+    env_vars: dict[str, dict[str, Any]] | None = None  # {"AWS_ENDPOINT_URL": {"template": "...", "description": "..."}}
+    instructions: str | None = None  # Markdown instructions template
 
 
 class SimsRegistry:
@@ -76,8 +81,9 @@ class SimsRegistry:
                     # Try to import the module to verify it's a valid sim
                     mod = importlib.import_module(modname)
 
-                    # Check if it looks like a sim (has Client or AsyncClient)
-                    if hasattr(mod, "Client") or hasattr(mod, "AsyncClient"):
+                    # Check if it looks like an API sim (has Client or AsyncClient)
+                    # or an instruction sim (has SERVICES)
+                    if hasattr(mod, "Client") or hasattr(mod, "AsyncClient") or hasattr(mod, "SERVICES"):
                         self._installed_sims[short_name] = mod
                 except ImportError:
                     continue
@@ -98,8 +104,10 @@ class SimsRegistry:
         # Check local specs dir if provided
         if self.specs_dir and self.specs_dir.exists():
             for d in self.specs_dir.iterdir():
-                if d.is_dir() and (d / "auth.yaml").exists():
-                    sims.add(d.name)
+                if d.is_dir():
+                    # Check for API sim (auth.yaml) or instruction sim (instructions.yaml)
+                    if (d / "auth.yaml").exists() or (d / "instructions.yaml").exists():
+                        sims.add(d.name)
 
         return sorted(sims)
 
@@ -120,6 +128,11 @@ class SimsRegistry:
             except Exception:
                 version = getattr(mod, "__version__", "unknown")
 
+            # Check if this is an instruction-based sim
+            if hasattr(mod, "SERVICES"):
+                return self._get_instruction_sim_info(name, mod, version)
+
+            # It's an API-based sim
             # Try to load auth config from package
             auth = None
             try:
@@ -141,12 +154,18 @@ class SimsRegistry:
                 description=mod.__doc__,
                 auth=auth,
                 base_url_suffix=base_url_suffix,
+                sim_type="api",
             )
 
         # Fall back to local specs dir
         if self.specs_dir:
             sim_dir = self.specs_dir / name
             auth_path = sim_dir / "auth.yaml"
+            instructions_path = sim_dir / "instructions.yaml"
+
+            # Check for instruction-based sim first
+            if instructions_path.exists():
+                return self._load_instruction_sim_from_file(name, instructions_path)
 
             if auth_path.exists():
                 auth = self._load_auth(auth_path)
@@ -157,10 +176,64 @@ class SimsRegistry:
                     description=None,
                     auth=auth,
                     base_url_suffix=None,
+                    sim_type="api",
                 )
 
         raise ValueError(f"Sim '{name}' not found")
 
+    def _get_instruction_sim_info(self, name: str, mod: Any, version: str) -> SimInfo:
+        """Get SimInfo for an instruction-based sim from its module."""
+        import importlib.resources
+
+        services = getattr(mod, "SERVICES", {})
+
+        # Try to load full config from bundled instructions.yaml
+        env_vars_config: dict[str, dict[str, Any]] = {}
+        instructions_text = ""
+        title = name.title()
+        description = mod.__doc__
+
+        try:
+            config_text = importlib.resources.files(mod.__name__).joinpath("instructions.yaml").read_text()
+            config_data = yaml.safe_load(config_text)
+            env_vars_config = config_data.get("env_vars", {})
+            instructions_text = config_data.get("instructions", "")
+            title = config_data.get("title", name.title())
+            description = config_data.get("description", mod.__doc__)
+        except Exception:
+            pass
+
+        return SimInfo(
+            name=name,
+            title=title,
+            version=version,
+            description=description,
+            auth=None,  # Instruction sims don't use auth config
+            base_url_suffix=None,
+            sim_type="instruction",
+            services=services,
+            env_vars=env_vars_config,
+            instructions=instructions_text,
+        )
+
+    def _load_instruction_sim_from_file(self, name: str, instructions_path: Path) -> SimInfo:
+        """Load instruction sim info from instructions.yaml file."""
+        with open(instructions_path) as f:
+            data = yaml.safe_load(f)
+
+        return SimInfo(
+            name=name,
+            title=data.get("title", name.title()),
+            version=data.get("version", "unknown"),
+            description=data.get("description"),
+            auth=None,
+            base_url_suffix=None,
+            sim_type="instruction",
+            services=data.get("services", {}),
+            env_vars=data.get("env_vars", {}),
+            instructions=data.get("instructions", ""),
+        )
+
     def _load_auth(self, auth_path: Path) -> AuthRequirement:
         """Load auth requirements from auth.yaml."""
         with open(auth_path) as f: