reuse-api 0.1.0__py3-none-any.whl

reuse_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: reuse-api
+Version: 0.1.0
+Summary: OpenAPI AI Readiness Scorecard & Sandbox — score and simulate your APIs for agentic use
+Project-URL: Homepage, https://sheepseb.github.io/cli-jentic
+Project-URL: Repository, https://github.com/SheepSeb/cli-jentic
+Project-URL: Bug Tracker, https://github.com/SheepSeb/cli-jentic/issues
+Author: SheepSeb
+License: MIT
+Keywords: agentic,agents,ai,api,llm,mock-server,openapi,sandbox,scorecard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: flask>=3
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: requests>=2.31
+Requires-Dist: typer[all]>=0.9
+Description-Content-Type: text/markdown
+
+# api-scorecard
+
+A CLI tool that scores OpenAPI specs for AI-readiness across 6 dimensions — giving APIs a letter grade and actionable recommendations so they work well with AI agents and LLM tooling.
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+## Usage
+
+### Scorecard
+
+```bash
+# Score an OpenAPI spec
+api-scorecard score path/to/openapi.yaml
+
+# Output as JSON
+api-scorecard score path/to/openapi.yaml --json
+
+# Run against the built-in sample spec to see how scoring works
+api-scorecard demo
+api-scorecard demo --json
+```
+
+### Sandbox
+
+The sandbox spins up a local mock server from your spec and auto-probes every endpoint, reporting a **feasibility score** — how well the spec can actually be exercised by an agent.
+
+```bash
+# Start a persistent mock server (press Ctrl+C to stop)
+api-scorecard sandbox start path/to/openapi.yaml
+api-scorecard sandbox start path/to/openapi.yaml --port 9000
+
+# Probe all endpoints and get a report
+api-scorecard sandbox probe path/to/openapi.yaml
+api-scorecard sandbox probe path/to/openapi.yaml --json
+
+# Run against the built-in sample spec
+api-scorecard sandbox demo
+api-scorecard sandbox demo --json
+```
+
+The `probe` command:
+1. Starts an internal mock server
+2. Generates synthetic request payloads and path parameters from the spec's schemas
+3. Fires requests at every operation
+4. Reports per-endpoint status codes, response times, and any issues found
+5. Exits with code `2` if the feasibility score is below 50%
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success / score ≥ threshold |
+| `1` | Error reading or parsing the spec |
+| `2` | Score below threshold (< 60 for scorecard, < 50% for sandbox) |
+
+## What gets scored
+
+Each spec is evaluated across 6 weighted dimensions:
+
+| Dimension | Weight | What it checks |
+|-----------|--------|----------------|
+| **Foundational Compliance** | 20% | OpenAPI version, `info` object, paths defined, spec validity |
+| **Developer Experience** | 15% | Operation IDs, summaries, request/response examples, parameter descriptions |
+| **AI-Readiness & Agent Experience** | 20% | Meaningful descriptions, error responses (4xx/5xx), response schemas, schema property descriptions |
+| **Agent Usability** | 20% | Semantic operation IDs, tag usage, parameter schemas, request body documentation |
+| **Security & Governance** | 15% | Security schemes defined, operations secured, auth documentation |
+| **AI Discoverability** | 10% | API-level description, tags defined, external docs |
+
+### Grading
+
+| Score | Grade |
+|-------|-------|
+| 90–100 | A |
+| 80–89 | B |
+| 70–79 | C |
+| 60–69 | D |
+| < 60 | F |
+
+## Example output
+
+```
+╭─ API AI Readiness Scorecard ──────────────────────────────────╮
+│  Task Manager API  v1.0.0                                      │
+│  sample_spec.yaml                                              │
+│                                                                │
+│  Overall Score: 42.3/100  Grade: F                             │
+╰────────────────────────────────────────────────────────────────╯
+
+╭──────────────────────────────────┬───────────┬───────┬──────────────────────────┬────────╮
+│ Dimension                        │     Score │ Grade │ Progress                 │ Issues │
+├──────────────────────────────────┼───────────┼───────┼──────────────────────────┼────────┤
+│ Foundational Compliance          │  75.0/100 │     C │ ███████████████░░░░░     │      1 │
+│ Developer Experience             │  38.5/100 │     F │ ███████░░░░░░░░░░░░░░    │      3 │
+│ AI-Readiness & Agent Experience  │  31.2/100 │     F │ ██████░░░░░░░░░░░░░░░    │      4 │
+│ ...                              │       ... │   ... │ ...                      │    ... │
+╰──────────────────────────────────┴───────────┴───────┴──────────────────────────┴────────╯
+
+Issues & Recommendations
+
+  AI-Readiness & Agent Experience
+    x 4/6 operations lack descriptive intent (need >30 char description)
+       paths.*.*.description
+    ! 5/6 operations have no documented error responses (4xx/5xx) — agents cannot handle failure gracefully
+       paths.*.*.responses
+```
+
+## JSON output
+
+Pass `--json` to get a machine-readable report:
+
+```bash
+api-scorecard score openapi.yaml --json | jq '.overall_score'
+```
+
+```json
+{
+  "api_name": "Task Manager API",
+  "api_version": "1.0.0",
+  "spec_path": "openapi.yaml",
+  "overall_score": 42.3,
+  "grade": "F",
+  "dimensions": [
+    {
+      "name": "Foundational Compliance",
+      "score": 75.0,
+      "grade": "C",
+      "issues": [...]
+    }
+  ]
+}
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv pip install -e .
+
+# Run directly without installing
+python main.py score path/to/spec.yaml
+```

reuse_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+sandbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sandbox/cli.py,sha256=Jl9CmFNt4capq3xoyNnZX_eGPQunue2GuwODq9qpVSw,4959
+sandbox/generator.py,sha256=qlmYRD2lRHwVxtqv6OEDXjARkmK14isYxGLOd7AQuWE,3325
+sandbox/models.py,sha256=Iur8o1GzXucDmOlDACU2W7B3KlvvKgJcuwcldtcophY,1098
+sandbox/prober.py,sha256=8LaT3bvghRHgXiGMJSCUNKw9--fbN9zWjmP3NOQK1g0,7530
+sandbox/report.py,sha256=gJzSH05tHVy5dooiF6QqXfzSlGVvW5djDwFr7Xq38FM,5369
+sandbox/server.py,sha256=rwZWvxcf13TkxjZz3NXzVWVDVVKo2oo5ng-e80HRk7w,5022
+scorecard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scorecard/cli.py,sha256=2Uk0THggLszo1C5Xw4BdN0xNPNXyDp2QZZjXYKtHxE4,2099
+scorecard/models.py,sha256=LaQ1J3Yx09UHK8a6iM9G94glTt3XPjyr75Vnckstdc0,890
+scorecard/parser.py,sha256=bx1mO6pxFNOGyCsR6To--5MoEzsUKTLT7EFxwLUZ0G4,511
+scorecard/report.py,sha256=JS2mP2eO3BwgVxbRX_DcJRT7WjPFgQXmDJDZhowDC_o,3396
+scorecard/scorer.py,sha256=2gI1d13gZR1rRJpUjr5-kk5xz_Rqtq7634asQmgP4Bk,1199
+scorecard/dimensions/__init__.py,sha256=1LX_26nfxvNZTrbSzMVvm1h-AZIhpHpnMKMPHlHgavs,1089
+scorecard/dimensions/agent_usability.py,sha256=WLezYSAtKkANV_4LrEnUdxS9inAwUaxp3YML3xIljIY,3444
+scorecard/dimensions/ai_readiness.py,sha256=3mY2W4WA9d09u4nJxTeWsJWCB8trahjdpsAVvUEHEOI,3774
+scorecard/dimensions/developer_experience.py,sha256=_r3BvdQ1z2t3CesaNrvV7SempjEejWdDvG7MPLBfFQo,4025
+scorecard/dimensions/discoverability.py,sha256=z_7zhTbnJl3xjbU5o4kpU0T03A7kFlr0OLVXdLuWICc,4263
+scorecard/dimensions/foundational.py,sha256=EDrHa90wAFD75YwlTQrdi376MrI6E7P65dhKNuOUNF4,2189
+scorecard/dimensions/security.py,sha256=WZiqEKDfmOmomc6-lTJr3EK8_CuB1vfS4Sl7Kd1RZY8,3556
+sandbox/data/sample_spec.yaml,sha256=MD6LXv2X2XccZ6KbjEh_8B19kHw-wohKYSgQ_Fz1H0Q,4208
+reuse_api-0.1.0.dist-info/METADATA,sha256=RT3joQGqtyz4kC9ajFjIxFx1rVr_J6OoE1xLB2tVRZI,6961
+reuse_api-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+reuse_api-0.1.0.dist-info/entry_points.txt,sha256=4U9qCI7DkIw2pTJyJlgbs8hGsCOFDQQdO3MoQV4Y_UE,52
+reuse_api-0.1.0.dist-info/RECORD,,

reuse_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

reuse_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+api-scorecard = scorecard.cli:app

sandbox/cli.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import socket
+import threading
+import time
+from pathlib import Path
+
+import typer
+from typing_extensions import Annotated
+from werkzeug.serving import make_server
+
+from scorecard.parser import load_spec
+from .server import create_app
+from .prober import probe_all
+from .models import SandboxReport
+from . import report as reporter
+
+sandbox_app = typer.Typer(
+    name="sandbox",
+    help="Run a mock server from an OpenAPI spec and probe its endpoints.",
+    add_completion=False,
+)
+
+_SAMPLE_SPEC = Path(__file__).parent / "data" / "sample_spec.yaml"
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+
+def _find_free_port(preferred: int) -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind((DEFAULT_HOST, preferred))
+            return preferred
+        except OSError:
+            s.bind((DEFAULT_HOST, 0))
+            return s.getsockname()[1]
+
+
+def _wait_for_server(host: str, port: int, timeout: float = 5.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=0.2):
+                return True
+        except OSError:
+            time.sleep(0.1)
+    return False
+
+
+def _load(spec_path: str) -> dict:
+    try:
+        return load_spec(spec_path)
+    except FileNotFoundError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)
+    except Exception as exc:
+        typer.echo(f"Error parsing spec: {exc}", err=True)
+        raise typer.Exit(1)
+
+
+@sandbox_app.command()
+def start(
+    spec: Annotated[str, typer.Argument(help="Path to OpenAPI spec file (JSON or YAML)")],
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to listen on")] = DEFAULT_PORT,
+) -> None:
+    """Start a local mock server from an OpenAPI spec. Press Ctrl+C to stop."""
+    spec_dict = _load(spec)
+    port = _find_free_port(port)
+    base_url = f"http://{DEFAULT_HOST}:{port}"
+
+    app = create_app(spec_dict)
+
+    reporter.console.print(f"\n[bold bright_magenta]Sandbox Mock Server[/]")
+    reporter.console.print(f"  Spec:  [dim]{spec}[/]")
+    reporter.console.print(f"  URL:   [bold]{base_url}[/]\n")
+    reporter.print_endpoints(spec_dict, base_url)
+    reporter.console.print("[dim]Press Ctrl+C to stop.[/]\n")
+
+    import logging
+    log = logging.getLogger("werkzeug")
+    log.setLevel(logging.ERROR)
+
+    srv = make_server(DEFAULT_HOST, port, app)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        reporter.console.print("\n[dim]Server stopped.[/]")
+
+
+def _probe(spec: str, port: int, as_json: bool) -> None:
+    spec_dict = _load(spec)
+    port = _find_free_port(port)
+    base_url = f"http://{DEFAULT_HOST}:{port}"
+
+    flask_app = create_app(spec_dict)
+
+    import logging
+    logging.getLogger("werkzeug").setLevel(logging.ERROR)
+
+    srv = make_server(DEFAULT_HOST, port, flask_app)
+    server_thread = threading.Thread(target=srv.serve_forever, daemon=True)
+    server_thread.start()
+
+    if not _wait_for_server(DEFAULT_HOST, port):
+        typer.echo("Error: mock server failed to start", err=True)
+        raise typer.Exit(1)
+
+    try:
+        if not as_json:
+            reporter.console.print(f"[dim]Mock server started at {base_url}. Probing endpoints...[/]\n")
+        results = probe_all(spec_dict, base_url)
+    finally:
+        srv.shutdown()
+
+    info = spec_dict.get("info") or {}
+    sandbox_report = SandboxReport(
+        api_name=info.get("title") or "Unknown API",
+        api_version=str(info.get("version") or "unknown"),
+        spec_path=spec,
+        base_url=base_url,
+        total_endpoints=len(results),
+        results=results,
+    )
+
+    if as_json:
+        reporter.print_json(sandbox_report)
+    else:
+        reporter.print_report(sandbox_report)
+
+    if sandbox_report.feasibility_score < 50:
+        raise typer.Exit(2)
+
+
+@sandbox_app.command()
+def probe(
+    spec: Annotated[str, typer.Argument(help="Path to OpenAPI spec file (JSON or YAML)")],
+    port: Annotated[int, typer.Option("--port", "-p", help="Port for the internal mock server")] = DEFAULT_PORT,
+    json: Annotated[bool, typer.Option("--json", help="Output results as JSON")] = False,
+) -> None:
+    """Auto-probe all endpoints against an internal mock server and show a feasibility report."""
+    _probe(spec=spec, port=port, as_json=json)
+
+
+@sandbox_app.command()
+def demo(
+    json: Annotated[bool, typer.Option("--json", help="Output results as JSON")] = False,
+) -> None:
+    """Probe the built-in sample spec (shows typical sandbox results)."""
+    if not _SAMPLE_SPEC.exists():
+        typer.echo("Error: sample_spec.yaml not found.", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"Running sandbox probe on built-in sample spec: {_SAMPLE_SPEC}\n")
+    _probe(spec=str(_SAMPLE_SPEC), port=DEFAULT_PORT, as_json=json)

sandbox/data/sample_spec.yaml

@@ -0,0 +1,163 @@
+openapi: "3.0.3"
+info:
+  title: "Task Manager API"
+  version: "1.0.0"
+  # Intentionally missing description
+
+paths:
+  /tasks:
+    get:
+      operationId: "listTasks"
+      summary: "List all tasks"
+      description: "Returns a paginated list of all tasks belonging to the current user."
+      tags: ["tasks"]
+      responses:
+        "200":
+          description: "A list of tasks"
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Task"
+        # Intentionally missing 4xx/5xx responses
+
+    post:
+      # Intentionally missing operationId
+      # Intentionally missing summary and description
+      # Intentionally missing tags
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTask"
+            # Intentionally missing example
+      responses:
+        "201":
+          description: "Task created successfully"
+        "400":
+          description: "Invalid input"
+
+  /tasks/{taskId}:
+    get:
+      operationId: "getTask"
+      summary: "Get a task by ID"
+      description: "Retrieves a specific task by its unique identifier."
+      tags: ["tasks"]
+      parameters:
+        - name: taskId
+          in: path
+          required: true
+          # Intentionally missing description
+          schema:
+            type: string
+      responses:
+        "200":
+          description: "The requested task"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Task"
+              example:
+                id: "abc123"
+                title: "Buy groceries"
+                done: false
+                createdAt: "2024-01-15T10:30:00Z"
+        "404":
+          description: "Task not found"
+
+    put:
+      operationId: "updateTask"
+      # Intentionally missing summary and description
+      # Intentionally missing tags
+      parameters:
+        - name: taskId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTask"
+      responses:
+        "200":
+          description: "Task updated"
+        # Intentionally missing error responses
+
+    delete:
+      # Intentionally missing operationId, summary, description, tags
+      parameters:
+        - name: taskId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: "Task deleted"
+        # Intentionally missing 404
+
+  /users:
+    get:
+      operationId: "op1"   # Intentionally bad operationId
+      # Intentionally missing summary, description, tags
+      responses:
+        "200":
+          description: "OK"
+          # Intentionally missing schema
+
+  /health:
+    get:
+      operationId: "healthCheck"
+      summary: "Health check"
+      description: "Returns the current health status of the API service."
+      tags: ["system"]
+      responses:
+        "200":
+          description: "Service is healthy"
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: "ok"
+
+# Intentionally no security schemes defined
+# Intentionally no global security
+
+components:
+  schemas:
+    Task:
+      type: object
+      properties:
+        id:
+          type: string
+          # Intentionally missing description
+        title:
+          type: string
+          description: "The task title"
+        done:
+          type: boolean
+          # Intentionally missing description
+        createdAt:
+          type: string
+          format: date-time
+          # Intentionally missing description
+
+    CreateTask:
+      type: object
+      required:
+        - title
+      properties:
+        title:
+          type: string
+          # Intentionally missing description
+        done:
+          type: boolean
+          # Intentionally missing description

sandbox/generator.py

@@ -0,0 +1,107 @@
+"""Generate synthetic values from JSON Schema definitions."""
+from __future__ import annotations
+from typing import Any
+
+
+_STRING_FORMAT_DEFAULTS: dict[str, Any] = {
+    "date-time": "2024-01-15T10:30:00Z",
+    "date": "2024-01-15",
+    "time": "10:30:00",
+    "email": "user@example.com",
+    "uri": "https://example.com",
+    "uuid": "123e4567-e89b-12d3-a456-426614174000",
+    "hostname": "example.com",
+    "ipv4": "127.0.0.1",
+    "password": "s3cr3t",
+    "byte": "dGVzdA==",
+    "binary": "binary-data",
+}
+
+
+def resolve_ref(ref: str, spec: dict) -> dict:
+    """Resolve a local $ref like '#/components/schemas/Task'."""
+    if not ref.startswith("#/"):
+        return {}
+    parts = ref[2:].split("/")
+    obj: Any = spec
+    for part in parts:
+        if not isinstance(obj, dict):
+            return {}
+        obj = obj.get(part, {})
+    return obj if isinstance(obj, dict) else {}
+
+
+def generate(schema: dict, spec: dict, _depth: int = 0) -> Any:
+    """Recursively generate a synthetic value that matches the given JSON Schema."""
+    if _depth > 6:
+        return None
+
+    # Resolve $ref
+    if "$ref" in schema:
+        schema = resolve_ref(schema["$ref"], spec)
+
+    # Inline example wins
+    if "example" in schema:
+        return schema["example"]
+
+    # allOf / anyOf / oneOf — use first branch
+    for keyword in ("allOf", "anyOf", "oneOf"):
+        if keyword in schema:
+            branches = schema[keyword]
+            if branches:
+                return generate(branches[0], spec, _depth + 1)
+
+    schema_type = schema.get("type")
+
+    if schema_type == "object" or "properties" in schema:
+        props = schema.get("properties") or {}
+        required = set(schema.get("required") or [])
+        result: dict[str, Any] = {}
+        for name, prop_schema in props.items():
+            if name in required or _depth == 0:
+                result[name] = generate(prop_schema, spec, _depth + 1)
+        return result
+
+    if schema_type == "array":
+        items = schema.get("items") or {}
+        return [generate(items, spec, _depth + 1)]
+
+    if schema_type == "string":
+        if "enum" in schema:
+            return schema["enum"][0]
+        fmt = schema.get("format", "")
+        return _STRING_FORMAT_DEFAULTS.get(fmt, schema.get("default", "string"))
+
+    if schema_type == "integer":
+        return schema.get("default", schema.get("minimum", 1))
+
+    if schema_type == "number":
+        return schema.get("default", schema.get("minimum", 1.0))
+
+    if schema_type == "boolean":
+        return schema.get("default", True)
+
+    if schema_type == "null":
+        return None
+
+    return schema.get("default")
+
+
+def generate_path_param(param: dict, spec: dict) -> str:
+    """Generate a URL-safe value for a path parameter."""
+    if "example" in param:
+        return str(param["example"])
+    schema = param.get("schema") or {}
+    if "$ref" in schema:
+        schema = resolve_ref(schema["$ref"], spec)
+    if "example" in schema:
+        return str(schema["example"])
+    if "enum" in schema:
+        return str(schema["enum"][0])
+    fmt = schema.get("format", "")
+    if fmt == "uuid":
+        return "123e4567-e89b-12d3-a456-426614174000"
+    param_type = schema.get("type", "string")
+    if param_type == "integer":
+        return "1"
+    return f"example-{param.get('name', 'id')}"

sandbox/models.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+from typing import Any, Literal
+from pydantic import BaseModel, computed_field
+
+
+class ProbeIssue(BaseModel):
+    severity: Literal["error", "warning", "info"]
+    message: str
+
+
+class ProbeResult(BaseModel):
+    path: str
+    method: str
+    status_code: int | None = None
+    success: bool
+    issues: list[ProbeIssue] = []
+    request_url: str
+    request_body: Any = None
+    response_body: Any = None
+    response_time_ms: float | None = None
+
+    @computed_field
+    @property
+    def label(self) -> str:
+        return f"{self.method.upper()} {self.path}"
+
+
+class SandboxReport(BaseModel):
+    api_name: str
+    api_version: str
+    spec_path: str
+    base_url: str
+    total_endpoints: int
+    results: list[ProbeResult]
+
+    @computed_field
+    @property
+    def successful(self) -> int:
+        return sum(1 for r in self.results if r.success)
+
+    @computed_field
+    @property
+    def feasibility_score(self) -> float:
+        if not self.total_endpoints:
+            return 0.0
+        return round((self.successful / self.total_endpoints) * 100, 1)