codi-api-agent 0.3.1__py3-none-any.whl

api_agent/graphql_loader.py

@@ -0,0 +1,309 @@
+"""Load a GraphQL API into the same read-only `Catalog` the rest of the pipeline uses.
+
+GraphQL doesn't map cleanly onto REST paths, so instead of converting to OpenAPI we read
+the schema natively (from a live endpoint via introspection, or a local SDL `.graphql` file)
+and build one `Tool` per **Query** field. This keeps the agent READ-ONLY by construction:
+mutations and subscriptions are recorded in the catalog's `reference` (so documentation mode can
+DESCRIBE them) but are never turned into callable tools.
+
+Each query tool's executor builds a GraphQL query string — `query(...) { field(args) { <auto
+selection> } }` — with an auto-generated selection set (scalar/enum fields, shallow object
+recursion), POSTs `{query, variables}` to the endpoint, and returns the same
+``{"ok","content","source","error"}`` contract as the OpenAPI executor (reusing `_compact_json`
+for PII redaction + size). GraphQL auth errors are surfaced as ``HTTP 401`` so the agent's
+existing re-auth handling kicks in.
+"""
+from __future__ import annotations
+
+import requests
+from graphql import (
+    GraphQLEnumType,
+    GraphQLInputObjectType,
+    GraphQLInterfaceType,
+    GraphQLList,
+    GraphQLNonNull,
+    GraphQLObjectType,
+    GraphQLScalarType,
+    build_client_schema,
+    build_schema,
+    get_introspection_query,
+)
+
+import requests
+
+from .catalog import Catalog, Tool
+from .openapi_loader import (
+    _UA,
+    READ_METHODS,
+    _compact_json,
+    _parse,
+    _redact_text,
+    _sanitize,
+    _unique,
+    build_catalog,
+    load_openapi,
+)
+from .spec_convert import CONVERTIBLE, convert_to_openapi, detect_format, set_base_url
+
+_SCALAR_JSON = {"Int": "integer", "Float": "number", "Boolean": "boolean",
+                "String": "string", "ID": "string"}
+_GQL_EXT = (".graphql", ".gql", ".graphqls", ".sdl")
+_AUTH_WORDS = ("unauthorized", "unauthenticated", "not authenticated", "forbidden",
+               "access denied", "permission", "login", "auth token", "must be logged in")
+
+
+# --------------------------------------------------------------------------- #
+# Public entry points
+# --------------------------------------------------------------------------- #
+def load_catalog(source: str, *, graphql: bool = False, endpoint: str | None = None,
+                 base_url: str | None = None, max_operations: int = 1000, timeout: int = 20,
+                 auth_header: str | None = None, auth_value: str | None = None) -> Catalog:
+    """One entry point for ANY spec format. Detects the source and dispatches:
+      - **GraphQL** (flag or `.graphql/.gql/.sdl`) → introspection/SDL loader.
+      - **OpenAPI / Swagger** → loaded directly.
+      - **Postman collection / RAML 0.8 / API Blueprint** → auto-CONVERTED to OpenAPI (via npx),
+        then loaded — so the user can point the agent at a non-OpenAPI spec and it just works.
+    `base_url` sets the server for a converted spec whose source left a `{{baseUrl}}`/no host
+    (Postman/RAML); `endpoint` is the GraphQL query URL for an SDL file."""
+    if graphql or source.lower().rstrip("/").endswith(_GQL_EXT):
+        return load_graphql(source, endpoint=endpoint, max_operations=max_operations,
+                            timeout=timeout, auth_header=auth_header, auth_value=auth_value)
+
+    # Read the raw source once, then detect its format.
+    if source.startswith(("http://", "https://")):
+        resp = requests.get(source, timeout=timeout, headers=_UA)
+        resp.raise_for_status()
+        text, origin = resp.text, source
+    else:
+        with open(source, encoding="utf-8") as f:
+            text, origin = f.read(), None
+    fmt = detect_format(text, source)
+
+    auth = (auth_header, auth_value) if auth_header and auth_value else None
+    if fmt in CONVERTIBLE:  # Postman / RAML / API Blueprint → convert to OpenAPI, then load
+        spec = convert_to_openapi(text, fmt)
+        if base_url:
+            spec = set_base_url(spec, base_url)
+        return build_catalog(spec, origin, methods=READ_METHODS,
+                             max_operations=max_operations, auth=auth)
+    # OpenAPI / Swagger / unknown → parse and load directly (single fetch, reuse the text).
+    return build_catalog(_parse(text), origin, methods=READ_METHODS,
+                         max_operations=max_operations, auth=auth)
+
+
+def load_graphql(source: str, endpoint: str | None = None, max_operations: int = 1000,
+                 timeout: int = 20, auth_header: str | None = None,
+                 auth_value: str | None = None) -> Catalog:
+    """Build a read-only Catalog from a GraphQL schema.
+
+    `source` is a live endpoint URL (introspected) or a local SDL file. For an SDL file you may
+    pass `endpoint` (the server to actually query); without it the tools document the schema but
+    can't be called. Auth header is injected into both introspection and query calls.
+    """
+    auth = (auth_header, auth_value) if auth_header and auth_value else None
+    schema, endpoint = _load_schema(source, endpoint, timeout, auth)
+
+    tools: list[Tool] = []
+    reference: list[dict] = []
+    seen: set[str] = set()
+
+    qtype = schema.query_type
+    if qtype:
+        for fname, field in qtype.fields.items():
+            if len(tools) >= max_operations:
+                break
+            name = _unique(_sanitize(fname), seen)
+            selection = _selection_set(field.type, depth=2, seen=frozenset())
+            arg_types = {a: str(arg.type) for a, arg in field.args.items()}
+            tools.append(Tool(
+                name=name,
+                description=_describe(fname, field),
+                parameters=_parameters(field),
+                data_type="structured",
+                fn=_make_executor(endpoint, fname, selection, arg_types, auth),
+            ))
+            reference.append(_reference_entry("query", fname, field))
+
+    # Mutations/subscriptions are documented but NEVER callable (read-only by construction).
+    for op_type, t in (("mutation", schema.mutation_type),
+                       ("subscription", schema.subscription_type)):
+        if t:
+            for fname, field in t.fields.items():
+                reference.append(_reference_entry(op_type, fname, field))
+
+    return Catalog(tools, reference=reference)
+
+
+# --------------------------------------------------------------------------- #
+# Schema loading
+# --------------------------------------------------------------------------- #
+def _load_schema(source: str, endpoint: str | None, timeout: int, auth):
+    if source.startswith(("http://", "https://")):
+        endpoint = endpoint or source
+        return build_client_schema(_introspect(source, timeout, auth)), endpoint
+    with open(source, encoding="utf-8") as f:
+        sdl = f.read()
+    # assume_valid: tolerate custom directives/scalars in third-party SDL dumps.
+    return build_schema(sdl, assume_valid=True), endpoint
+
+
+def _introspect(url: str, timeout: int, auth) -> dict:
+    headers = {**_UA, "Content-Type": "application/json"}
+    if auth:
+        headers[auth[0]] = auth[1]
+    resp = requests.post(url, json={"query": get_introspection_query(descriptions=True)},
+                         headers=headers, timeout=timeout)
+    resp.raise_for_status()
+    payload = resp.json()
+    if not payload.get("data"):
+        raise ValueError(f"GraphQL introspection failed: {payload.get('errors')}")
+    return payload["data"]
+
+
+# --------------------------------------------------------------------------- #
+# Type / selection helpers
+# --------------------------------------------------------------------------- #
+def _unwrap(t):
+    """Strip NonNull/List wrappers to the underlying named type."""
+    while isinstance(t, (GraphQLNonNull, GraphQLList)):
+        t = t.of_type
+    return t
+
+
+def _json_type(gtype) -> dict:
+    """Map a GraphQL type to a JSON-schema fragment for the tool's parameter spec."""
+    if isinstance(gtype, GraphQLNonNull):
+        return _json_type(gtype.of_type)
+    if isinstance(gtype, GraphQLList):
+        return {"type": "array", "items": _json_type(gtype.of_type)}
+    if isinstance(gtype, GraphQLScalarType):
+        return {"type": _SCALAR_JSON.get(gtype.name, "string")}
+    if isinstance(gtype, GraphQLEnumType):
+        return {"type": "string", "enum": list(gtype.values.keys())}
+    if isinstance(gtype, GraphQLInputObjectType):
+        return {"type": "object"}  # opaque input object — the model supplies a dict
+    return {"type": "string"}
+
+
+def _selection_set(gtype, depth: int, seen: frozenset) -> str:
+    """Auto-build a selection set: all scalar/enum fields, recursing shallowly into object
+    fields, skipping fields that REQUIRE arguments (can't be auto-filled) and avoiding type
+    cycles. Returns '' for leaf (scalar) return types — they need no sub-selection."""
+    t = _unwrap(gtype)
+    if isinstance(t, (GraphQLScalarType, GraphQLEnumType)):
+        return ""
+    if not isinstance(t, (GraphQLObjectType, GraphQLInterfaceType)):
+        return ""  # union/input — skip rather than guess
+    if t.name in seen or depth <= 0:
+        return "{ __typename }"  # minimal valid selection to stop recursion
+    seen = seen | {t.name}
+    parts: list[str] = []
+    for fname, f in t.fields.items():
+        if any(isinstance(a.type, GraphQLNonNull) for a in f.args.values()):
+            continue  # needs required args we can't supply
+        inner = _unwrap(f.type)
+        if isinstance(inner, (GraphQLScalarType, GraphQLEnumType)):
+            parts.append(fname)
+        elif isinstance(inner, (GraphQLObjectType, GraphQLInterfaceType)) and depth > 1:
+            sub = _selection_set(f.type, depth - 1, seen)
+            if sub:
+                parts.append(f"{fname} {sub}")
+        if len(parts) >= 20:  # cap breadth so queries stay reasonable
+            break
+    return "{ " + " ".join(parts) + " }" if parts else "{ __typename }"
+
+
+def _describe(fname: str, field) -> str:
+    desc = (field.description or "").strip()
+    head = f"GraphQL query `{fname}` → {field.type}."
+    return (head + (" " + desc if desc else "")).strip()
+
+
+def _parameters(field) -> dict:
+    props: dict = {}
+    required: list[str] = []
+    for aname, arg in field.args.items():
+        sch = _json_type(arg.type)
+        if arg.description:
+            sch["description"] = arg.description.strip()[:160]
+        props[aname] = sch
+        if isinstance(arg.type, GraphQLNonNull):
+            required.append(aname)
+    return {"type": "object", "properties": props, "required": required}
+
+
+def _reference_entry(op_type: str, fname: str, field) -> dict:
+    """Documentation record for one GraphQL field. `method` maps query->GET (callable read),
+    mutation->POST, subscription->SUBSCRIPTION so the agent's existing GET/HEAD-vs-write logic
+    treats them correctly."""
+    method = {"query": "GET", "mutation": "POST", "subscription": "SUBSCRIPTION"}[op_type]
+    desc = (field.description or "").strip()
+    return {
+        "name": _sanitize(fname),
+        "method": method,
+        "path": fname,
+        "summary": (desc.split("\n", 1)[0][:120] or f"{op_type} → {field.type}"),
+        "description": desc[:300],
+        "params": [
+            {"name": a, "in": "query", "required": isinstance(arg.type, GraphQLNonNull),
+             "type": _json_type(arg.type).get("type", "string"), "example": None}
+            for a, arg in field.args.items()
+        ],
+        "body": [],
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Execution
+# --------------------------------------------------------------------------- #
+def _build_query(field_name: str, selection: str, arg_gql_types: dict, provided: dict) -> str:
+    """Compose a GraphQL query using ONLY the args the model supplied (so optional args are
+    simply omitted and required-but-missing args surface as a server error, not a silent null)."""
+    var_defs = ", ".join(f"${k}: {arg_gql_types[k]}" for k in provided)
+    call_args = ", ".join(f"{k}: ${k}" for k in provided)
+    head = f"query({var_defs})" if var_defs else "query"
+    call = f"{field_name}({call_args})" if call_args else field_name
+    return f"{head} {{ {call} {selection} }}".replace("  ", " ").strip()
+
+
+def _make_executor(endpoint: str | None, field_name: str, selection: str,
+                   arg_gql_types: dict, auth):
+    def fn(args: dict, timeout: int, list_limit: int | None = None) -> dict:
+        n = list_limit or 50  # how many items of a list response to keep (per-query override)
+        if not endpoint:
+            return {"ok": False, "content": "", "source": "",
+                    "error": "No GraphQL endpoint configured for this schema — add the server URL "
+                    "so I can run queries (the schema only documents the operations)."}
+        provided = {k: v for k, v in (args or {}).items()
+                    if v is not None and k in arg_gql_types}
+        query = _build_query(field_name, selection, arg_gql_types, provided)
+        headers = {**_UA, "Content-Type": "application/json"}
+        if auth:
+            headers[auth[0]] = auth[1]
+        try:
+            resp = requests.post(endpoint, json={"query": query, "variables": provided},
+                                 headers=headers, timeout=timeout)
+        except Exception as e:
+            return {"ok": False, "error": str(e), "content": "", "source": endpoint}
+        if resp.status_code >= 400:
+            return {"ok": False, "error": f"HTTP {resp.status_code}",
+                    "content": resp.text[:500], "source": endpoint}
+        try:
+            payload = resp.json()
+        except Exception:
+            return {"ok": False, "error": "Non-JSON response from GraphQL endpoint",
+                    "content": _redact_text(resp.text[:500]), "source": endpoint}
+        errors = payload.get("errors")
+        data = payload.get("data")
+        result = data.get(field_name) if isinstance(data, dict) else None
+        # Surface the error only when nothing usable came back; if data is present (even partial),
+        # prefer returning it. Map auth-ish GraphQL errors to 401 for the agent's re-auth handling.
+        if errors and result is None and not data:
+            msg = "; ".join(e.get("message", "") for e in errors[:3] if isinstance(e, dict))
+            if any(w in msg.lower() for w in _AUTH_WORDS):
+                return {"ok": False, "error": f"HTTP 401 — {msg[:200]}", "content": "", "source": endpoint}
+            return {"ok": False, "error": f"GraphQL error: {msg[:300]}", "content": "", "source": endpoint}
+        content = _compact_json(result if result is not None else data, max_items=n)
+        return {"ok": True, "content": content[: max(8000, n * 600)], "source": endpoint}
+
+    return fn