openapi-to-agent-skills 0.3.2__tar.gz

openapi_to_agent_skills-0.3.2/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Test output
+test-output/
+test-output-e2e/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.whl
+*.tar.gz

openapi_to_agent_skills-0.3.2/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: openapi-to-agent-skills
+Version: 0.3.2
+Summary: Convert OpenAPI specifications to Agent Skills format
+Project-URL: Homepage, https://github.com/xuyong/openapi-to-agent-skills
+Project-URL: Repository, https://github.com/xuyong/openapi-to-agent-skills
+Author: Xu Yong
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: regex>=2024.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openapi-to-agent-skills
+
+Convert OpenAPI specifications to Agent Skills format — structured markdown documentation optimized for AI agents.
+
+## Installation
+
+```bash
+pip install openapi-to-agent-skills
+```
+
+## Usage
+
+```bash
+openapi-to-agent-skills <path-or-url-to-openapi-spec> [OPTIONS]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output` | Output directory | `./output` |
+| `-n, --name` | Skill name (derived from API title if omitted) | |
+| `--include-tags` | Only include these tags (comma-separated) | |
+| `--exclude-tags` | Exclude these tags (comma-separated) | |
+| `--exclude-deprecated` | Exclude deprecated operations | `False` |
+| `-t, --templates` | Custom templates directory | |
+| `-a, --assets` | Static assets directory overlaid onto output | |
+| `--exclude-paths` | Exclude paths matching prefixes (comma-separated) | |
+| `-g, --group-by` | Grouping strategy: `tags`, `path`, `auto` | `auto` |
+| `--case-strategy` | `lowercase` for case-insensitive filesystem safety | |
+| `-f, --force` | Overwrite existing output directory | `False` |
+| `-q, --quiet` | Suppress output except errors | `False` |
+
+### Examples
+
+```bash
+# From a local file
+openapi-to-agent-skills api.yaml -o ./skills
+
+# From a URL
+openapi-to-agent-skills https://petstore3.swagger.io/api/v3/openapi.json -o ./skills
+
+# Filter by tags
+openapi-to-agent-skills api.yaml --include-tags users,orders
+
+# Case-safe output for Windows/macOS
+openapi-to-agent-skills api.yaml --case-strategy lowercase
+```
+
+## Output Structure
+
+```
+<skill-name>/
+├── SKILL.md                          # Entry point with YAML frontmatter
+└── references/
+    ├── authentication.md             # Auth schemes (if any)
+    ├── resources/
+    │   └── <tag>.md                  # One per resource group
+    ├── operations/
+    │   └── <operationId>.md          # One per operation
+    └── schemas/
+        └── <prefix>/
+            ├── _index.md
+            └── <SchemaName>.md       # One per schema
+```
+
+## Programmatic Usage
+
+```python
+from openapi_to_skills import convert_openapi_to_skill
+from openapi_to_skills.types import ConvertOptions
+
+import yaml
+
+with open("api.yaml") as f:
+    spec = yaml.safe_load(f)
+
+convert_openapi_to_skill(spec, ConvertOptions(output_dir="./output"))
+```
+
+## License
+
+MIT

openapi_to_agent_skills-0.3.2/README.md

@@ -0,0 +1,83 @@
+# openapi-to-agent-skills
+
+Convert OpenAPI specifications to Agent Skills format — structured markdown documentation optimized for AI agents.
+
+## Installation
+
+```bash
+pip install openapi-to-agent-skills
+```
+
+## Usage
+
+```bash
+openapi-to-agent-skills <path-or-url-to-openapi-spec> [OPTIONS]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output` | Output directory | `./output` |
+| `-n, --name` | Skill name (derived from API title if omitted) | |
+| `--include-tags` | Only include these tags (comma-separated) | |
+| `--exclude-tags` | Exclude these tags (comma-separated) | |
+| `--exclude-deprecated` | Exclude deprecated operations | `False` |
+| `-t, --templates` | Custom templates directory | |
+| `-a, --assets` | Static assets directory overlaid onto output | |
+| `--exclude-paths` | Exclude paths matching prefixes (comma-separated) | |
+| `-g, --group-by` | Grouping strategy: `tags`, `path`, `auto` | `auto` |
+| `--case-strategy` | `lowercase` for case-insensitive filesystem safety | |
+| `-f, --force` | Overwrite existing output directory | `False` |
+| `-q, --quiet` | Suppress output except errors | `False` |
+
+### Examples
+
+```bash
+# From a local file
+openapi-to-agent-skills api.yaml -o ./skills
+
+# From a URL
+openapi-to-agent-skills https://petstore3.swagger.io/api/v3/openapi.json -o ./skills
+
+# Filter by tags
+openapi-to-agent-skills api.yaml --include-tags users,orders
+
+# Case-safe output for Windows/macOS
+openapi-to-agent-skills api.yaml --case-strategy lowercase
+```
+
+## Output Structure
+
+```
+<skill-name>/
+├── SKILL.md                          # Entry point with YAML frontmatter
+└── references/
+    ├── authentication.md             # Auth schemes (if any)
+    ├── resources/
+    │   └── <tag>.md                  # One per resource group
+    ├── operations/
+    │   └── <operationId>.md          # One per operation
+    └── schemas/
+        └── <prefix>/
+            ├── _index.md
+            └── <SchemaName>.md       # One per schema
+```
+
+## Programmatic Usage
+
+```python
+from openapi_to_skills import convert_openapi_to_skill
+from openapi_to_skills.types import ConvertOptions
+
+import yaml
+
+with open("api.yaml") as f:
+    spec = yaml.safe_load(f)
+
+convert_openapi_to_skill(spec, ConvertOptions(output_dir="./output"))
+```
+
+## License
+
+MIT

openapi_to_agent_skills-0.3.2/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "openapi-to-agent-skills"
+version = "0.3.2"
+description = "Convert OpenAPI specifications to Agent Skills format"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Xu Yong" },
+]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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 :: Software Development :: Code Generators",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "pyyaml>=6.0",
+    "jinja2>=3.1.0",
+    "httpx>=0.27.0",
+    "rich>=13.0",
+    "regex>=2024.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/xuyong/openapi-to-agent-skills"
+Repository = "https://github.com/xuyong/openapi-to-agent-skills"
+
+[project.scripts]
+openapi-to-agent-skills = "openapi_to_skills.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openapi_to_skills"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

openapi_to_agent_skills-0.3.2/src/openapi_to_skills/__init__.py

@@ -0,0 +1,5 @@
+"""OpenAPI to Skills - Convert OpenAPI specifications to Agent Skills format."""
+
+from openapi_to_skills.converter import convert_openapi_to_skill
+
+__all__ = ["convert_openapi_to_skill"]

openapi_to_agent_skills-0.3.2/src/openapi_to_skills/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for python -m openapi_to_skills."""
+
+from openapi_to_skills.cli import app
+
+app()

openapi_to_agent_skills-0.3.2/src/openapi_to_skills/cli.py

@@ -0,0 +1,133 @@
+"""CLI entry point using Typer."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from openapi_to_skills.converter import convert_openapi_to_skill
+from openapi_to_skills.renderer import to_file_name
+from openapi_to_skills.spec_loader import load_spec_from_input
+from openapi_to_skills.types import ConvertOptions, ParserFilter, ParserOptions
+from openapi_to_skills.validate import validate_case_strategy, validate_group_by, validate_spec
+
+app = typer.Typer(add_completion=False)
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.command()
+def main(
+    input_path: str = typer.Argument(..., help="Path or URL to OpenAPI spec (JSON or YAML)"),
+    output: str = typer.Option("./output", "-o", "--output", help="Output directory"),
+    name: Optional[str] = typer.Option(None, "-n", "--name", help="Skill name (default: derived from API title)"),
+    include_tags: Optional[str] = typer.Option(None, "--include-tags", help="Only include these tags (comma-separated)"),
+    exclude_tags: Optional[str] = typer.Option(None, "--exclude-tags", help="Exclude these tags (comma-separated)"),
+    exclude_deprecated: bool = typer.Option(False, "--exclude-deprecated", help="Exclude deprecated operations"),
+    templates: Optional[str] = typer.Option(None, "-t", "--templates", help="Custom templates directory"),
+    assets: Optional[str] = typer.Option(None, "-a", "--assets", help="Static assets directory overlaid onto the skill after generation"),
+    exclude_paths: Optional[str] = typer.Option(None, "--exclude-paths", help="Exclude paths matching these prefixes (comma-separated)"),
+    group_by: str = typer.Option("auto", "-g", "--group-by", help="How to group operations: tags, path, auto"),
+    case_strategy: Optional[str] = typer.Option(None, "--case-strategy", help="Strategy for case-insensitive filesystem safety: lowercase"),
+    force: bool = typer.Option(False, "-f", "--force", help="Overwrite existing output directory"),
+    quiet: bool = typer.Option(False, "-q", "--quiet", help="Suppress output except errors"),
+) -> None:
+    """Convert OpenAPI specifications to Agent Skills format."""
+    if not quiet:
+        console.print(f"[bold]Reading OpenAPI spec:[/bold] {input_path}")
+
+    try:
+        spec = load_spec_from_input(input_path)
+    except Exception as e:
+        err_console.print(f"[red]Error loading spec:[/red] {e}")
+        raise typer.Exit(1)
+
+    # Validate spec
+    spec_error = validate_spec(spec)
+    if spec_error:
+        err_console.print(f"[red]Error:[/red] {spec_error}")
+        raise typer.Exit(1)
+
+    # Validate options
+    try:
+        validated_group_by = validate_group_by(group_by)
+        validated_case_strategy = validate_case_strategy(case_strategy)
+    except ValueError as e:
+        err_console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    # Derive skill name for output path check
+    skill_name = name or to_file_name(spec["info"]["title"]).lower()[:64]
+    output_path = os.path.join(output, skill_name)
+
+    # Check if output exists
+    if os.path.exists(output_path):
+        if not force:
+            err_console.print(
+                f"[red]Error:[/red] Output directory already exists: {output_path}\nUse --force to overwrite.",
+            )
+            raise typer.Exit(1)
+        shutil.rmtree(output_path)
+
+    # Validate assets dir
+    if assets:
+        if not os.path.exists(assets):
+            console.print(f"[red]Error:[/red] Assets directory not found: {assets}")
+            raise typer.Exit(1)
+        assets_abs = os.path.abspath(assets)
+        output_abs = os.path.abspath(output_path)
+        if assets_abs == output_abs or assets_abs.startswith(output_abs + os.sep):
+            err_console.print(
+                f"[red]Error:[/red] Assets directory must be outside the output directory: {assets}",
+            )
+            raise typer.Exit(1)
+
+    if not quiet:
+        console.print(f"  API: {spec['info']['title']} (v{spec['info'].get('version', '')})")
+        console.print(f"  OpenAPI version: {spec.get('openapi', '')}")
+        console.print(f"  Paths: {len(spec.get('paths', {}))}")
+        tags_list = spec.get("tags", [])
+        tag_names = ", ".join(t["name"] for t in tags_list) if tags_list else "none"
+        console.print(f"  Tags: {tag_names}")
+        schemas = (spec.get("components") or {}).get("schemas")
+        if schemas:
+            console.print(f"  Schemas: {len(schemas)}")
+        console.print("[bold]Converting to Agent Skill...[/bold]")
+
+    # Build options
+    parser_filter = ParserFilter(
+        include_tags=[t.strip() for t in include_tags.split(",")] if include_tags else None,
+        exclude_tags=[t.strip() for t in exclude_tags.split(",")] if exclude_tags else None,
+        exclude_deprecated=exclude_deprecated,
+        exclude_paths=[p.strip() for p in exclude_paths.split(",")] if exclude_paths else None,
+    )
+    parser_options = ParserOptions(
+        skill_name=name,
+        filter=parser_filter,
+        group_by=validated_group_by,
+    )
+    convert_options = ConvertOptions(
+        output_dir=output,
+        parser=parser_options,
+        template_dir=templates,
+        case_strategy=validated_case_strategy,
+        assets_dir=assets,
+    )
+
+    try:
+        convert_openapi_to_skill(spec, convert_options)
+    except Exception as e:
+        console.print(f"[red]Error during conversion:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not quiet:
+        console.print(f"[green]Skill generated at:[/green] {output_path}")
+
+
+if __name__ == "__main__":
+    app()

openapi_to_agent_skills-0.3.2/src/openapi_to_skills/converter.py

@@ -0,0 +1,139 @@
+"""Converter: orchestrates Parser -> Renderer -> Writer pipeline."""
+
+from __future__ import annotations
+
+import os
+
+from openapi_to_skills.parser import create_parser
+from openapi_to_skills.renderer import create_renderer, to_file_name
+from openapi_to_skills.types import (
+    ConvertOptions,
+    SchemaDocument,
+    SchemaGroupDocument,
+    SkillDocument,
+)
+from openapi_to_skills.writer import create_writer
+
+
+def convert_openapi_to_skill(spec: dict, options: ConvertOptions) -> None:
+    parser = create_parser()
+    renderer = create_renderer(options.template_dir)
+    writer = create_writer()
+
+    # Parse OpenAPI to IR
+    doc = parser.parse(spec, options.parser)
+
+    # Apply case strategy to IR before rendering
+    if options.case_strategy == "lowercase":
+        doc = _apply_case_strategy_lowercase(doc)
+
+    # Write output
+    _write_skill_output(doc, options.output_dir, renderer, writer)
+
+    # Overlay hand-authored static assets
+    if options.assets_dir:
+        skill_dir = os.path.join(options.output_dir, doc.meta.name)
+        writer.copy_dir(options.assets_dir, skill_dir)
+
+
+def _apply_case_strategy_lowercase(doc: SkillDocument) -> SkillDocument:
+    """Merge schema groups by case-insensitive prefix, lowercase names, disambiguate."""
+    merged_map: dict[str, dict] = {}
+
+    for group in doc.schema_groups:
+        key = group.prefix.lower()
+        if key in merged_map:
+            merged_map[key]["schemas"].extend(group.schemas)
+        else:
+            merged_map[key] = {"prefix": key, "schemas": list(group.schemas)}
+
+    new_groups: list[SchemaGroupDocument] = []
+    for entry in merged_map.values():
+        used_names: set[str] = set()
+        renamed_schemas: list[SchemaDocument] = []
+
+        for schema in entry["schemas"]:
+            base_name = to_file_name(schema.name).lower()
+            final_name = base_name
+            counter = 2
+
+            while final_name in used_names:
+                final_name = f"{base_name}-{counter}"
+                counter += 1
+
+            used_names.add(final_name)
+            renamed_schemas.append(
+                SchemaDocument(
+                    name=final_name,
+                    type=schema.type,
+                    description=schema.description,
+                    fields=schema.fields,
+                    enum_values=schema.enum_values,
+                    composition=schema.composition,
+                    items=schema.items,
+                )
+            )
+
+        new_groups.append(SchemaGroupDocument(prefix=entry["prefix"], schemas=renamed_schemas))
+
+    return SkillDocument(
+        meta=doc.meta,
+        resources=doc.resources,
+        schema_groups=new_groups,
+        auth_schemes=doc.auth_schemes,
+    )
+
+
+def _write_skill_output(doc: SkillDocument, output_dir: str, renderer, writer) -> None:
+    skill_dir = os.path.join(output_dir, doc.meta.name)
+    references_dir = os.path.join(skill_dir, "references")
+    resources_dir = os.path.join(references_dir, "resources")
+    operations_dir = os.path.join(references_dir, "operations")
+    schemas_dir = os.path.join(references_dir, "schemas")
+
+    # Create directories
+    writer.mkdir(skill_dir)
+    if doc.resources:
+        writer.mkdir(resources_dir)
+        writer.mkdir(operations_dir)
+    if doc.schema_groups:
+        writer.mkdir(schemas_dir)
+
+    # Write SKILL.md
+    skill_md = renderer.render_skill(doc)
+    writer.write_file(os.path.join(skill_dir, "SKILL.md"), skill_md)
+
+    # Write resources and operations
+    for resource in doc.resources:
+        file_name = to_file_name(resource.tag)
+
+        # Resource index
+        resource_md = renderer.render_resource(resource)
+        writer.write_file(os.path.join(resources_dir, f"{file_name}.md"), resource_md)
+
+        # Individual operation files
+        for op in resource.operations:
+            op_file_name = to_file_name(op.operation_id)
+            op_md = renderer.render_operation(op)
+            writer.write_file(os.path.join(operations_dir, f"{op_file_name}.md"), op_md)
+
+    # Write schema groups
+    for group in doc.schema_groups:
+        prefix_dir = os.path.join(schemas_dir, to_file_name(group.prefix))
+        writer.mkdir(prefix_dir)
+
+        # Schema index
+        index_md = renderer.render_schema_index(group)
+        writer.write_file(os.path.join(prefix_dir, "_index.md"), index_md)
+
+        # Individual schema files
+        for schema in group.schemas:
+            schema_md = renderer.render_schema(schema)
+            writer.write_file(
+                os.path.join(prefix_dir, f"{to_file_name(schema.name)}.md"), schema_md
+            )
+
+    # Write authentication
+    if doc.auth_schemes:
+        auth_md = renderer.render_authentication(doc.auth_schemes)
+        writer.write_file(os.path.join(references_dir, "authentication.md"), auth_md)