anip-graphql 0.11.0__tar.gz

anip_graphql-0.11.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: anip-graphql
+Version: 0.11.0
+Summary: ANIP GraphQL bindings — expose ANIPService capabilities via GraphQL
+Author-email: ANIP Protocol <team@anip.dev>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/anip-protocol/anip
+Keywords: anip,agent,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: anip-service==0.11.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: ariadne>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"

anip_graphql-0.11.0/README.md

@@ -0,0 +1,15 @@
+# anip-graphql
+
+ANIP GraphQL bindings — expose ANIPService capabilities via GraphQL
+
+Part of the [ANIP](https://github.com/anip-protocol/anip) protocol ecosystem.
+
+## Install
+
+```bash
+pip install anip-graphql
+```
+
+## Documentation
+
+See the [ANIP repository](https://github.com/anip-protocol/anip) for full documentation.

anip_graphql-0.11.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "anip-graphql"
+version = "0.11.0"
+description = "ANIP GraphQL bindings — expose ANIPService capabilities via GraphQL"
+requires-python = ">=3.11"
+dependencies = [
+    "anip-service==0.11.0",
+    "fastapi>=0.115.0",
+    "ariadne>=0.24.0",
+]
+authors = [{ name = "ANIP Protocol", email = "team@anip.dev" }]
+license = { text = "Apache-2.0" }
+keywords = ["anip", "agent", "protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Repository = "https://github.com/anip-protocol/anip"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.setuptools.packages.find]
+where = ["src"]

anip_graphql-0.11.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

anip_graphql-0.11.0/src/anip_graphql/__init__.py

@@ -0,0 +1,4 @@
+"""ANIP GraphQL bindings — expose ANIPService capabilities via GraphQL."""
+from .routes import mount_anip_graphql
+
+__all__ = ["mount_anip_graphql"]

anip_graphql-0.11.0/src/anip_graphql/routes.py

@@ -0,0 +1,157 @@
+"""ANIP GraphQL bindings — mount a GraphQL endpoint on a FastAPI app."""
+from __future__ import annotations
+
+from typing import Any
+
+from ariadne import QueryType, MutationType, ScalarType, make_executable_schema
+from ariadne.asgi import GraphQL
+from fastapi import FastAPI
+from fastapi.responses import PlainTextResponse
+
+from anip_service import ANIPService, ANIPError
+from .translation import (
+    generate_schema,
+    build_graphql_response,
+    to_camel_case,
+    to_snake_case,
+)
+
+
+async def _resolve_auth(request, service: ANIPService, capability_name: str):
+    """Resolve auth — JWT first, then API key."""
+    auth = request.headers.get("authorization", "")
+    if not auth.startswith("Bearer "):
+        return None
+    bearer = auth[7:].strip()
+
+    # Try as JWT first — preserves original delegation chain
+    jwt_error = None
+    try:
+        return await service.resolve_bearer_token(bearer)
+    except ANIPError as e:
+        jwt_error = e
+
+    # Try as API key — only if JWT failed
+    principal = await service.authenticate_bearer(bearer)
+    if principal:
+        cap_decl = service.get_capability_declaration(capability_name)
+        min_scope = cap_decl.minimum_scope if cap_decl else []
+        token_result = await service.issue_token(principal, {
+            "subject": "adapter:anip-graphql",
+            "scope": min_scope if min_scope else ["*"],
+            "capability": capability_name,
+            "purpose_parameters": {"source": "graphql"},
+        })
+        return await service.resolve_bearer_token(token_result["token"])
+
+    # Surface the original JWT error
+    if jwt_error:
+        raise jwt_error
+    return None
+
+
+def _make_resolver(capability_name: str, service: ANIPService):
+    """Create a resolver for a given capability."""
+
+    async def resolver(_obj: Any, info: Any, **kwargs: Any) -> dict[str, Any]:
+        # Convert camelCase args back to snake_case
+        arguments = {to_snake_case(k): v for k, v in kwargs.items()}
+
+        try:
+            token = await _resolve_auth(info.context["request"], service, capability_name)
+        except ANIPError as e:
+            return build_graphql_response({
+                "success": False,
+                "failure": {
+                    "type": e.error_type,
+                    "detail": e.detail,
+                    "resolution": e.resolution,
+                    "retry": e.retry,
+                },
+            })
+
+        if token is None:
+            return build_graphql_response({
+                "success": False,
+                "failure": {
+                    "type": "authentication_required",
+                    "detail": "Authorization header required",
+                    "resolution": {"action": "provide_credentials"},
+                    "retry": True,
+                },
+            })
+
+        try:
+            result = await service.invoke(capability_name, token, arguments)
+        except ANIPError as e:
+            return build_graphql_response({
+                "success": False,
+                "failure": {
+                    "type": e.error_type,
+                    "detail": e.detail,
+                    "resolution": e.resolution,
+                    "retry": e.retry,
+                },
+            })
+
+        return build_graphql_response(result)
+
+    return resolver
+
+
+def mount_anip_graphql(
+    app: FastAPI,
+    service: ANIPService,
+    *,
+    path: str = "/graphql",
+    prefix: str = "",
+    debug: bool = False,
+) -> None:
+    """Mount a GraphQL endpoint on a FastAPI app.
+
+    Args:
+        app: FastAPI app instance.
+        service: ANIPService to expose.
+        path: GraphQL endpoint path. Default: "/graphql".
+        prefix: URL prefix.
+    """
+    manifest = service.get_manifest()
+    capabilities = {}
+    for name in manifest.capabilities:
+        decl = service.get_capability_declaration(name)
+        if decl:
+            capabilities[name] = decl
+
+    schema_sdl = generate_schema(capabilities)
+
+    # Build Ariadne resolvers
+    query = QueryType()
+    mutation = MutationType()
+    json_scalar = ScalarType("JSON")
+
+    @json_scalar.serializer
+    def serialize_json(value):
+        return value
+
+    @json_scalar.value_parser
+    def parse_json_value(value):
+        return value
+
+    for name, decl in capabilities.items():
+        camel_name = to_camel_case(name)
+        resolver_fn = _make_resolver(name, service)
+        se_type = decl.side_effect.type.value if hasattr(decl.side_effect.type, "value") else str(decl.side_effect.type)
+        if se_type == "read":
+            query.field(camel_name)(resolver_fn)
+        else:
+            mutation.field(camel_name)(resolver_fn)
+
+    schema = make_executable_schema(schema_sdl, query, mutation, json_scalar)
+    graphql_app = GraphQL(schema, debug=debug)
+
+    full_path = f"{prefix}{path}"
+    app.mount(full_path, graphql_app)
+
+    @app.get(f"{prefix}/schema.graphql")
+    async def get_schema() -> PlainTextResponse:
+        return PlainTextResponse(schema_sdl, media_type="text/plain")

anip_graphql-0.11.0/src/anip_graphql/translation.py

@@ -0,0 +1,161 @@
+"""ANIP → GraphQL translation layer.
+
+Generates SDL schema from ANIP capabilities with custom directives,
+camelCase field names, and query/mutation separation.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from anip_core.models import CapabilityDeclaration
+
+
+def to_camel_case(snake: str) -> str:
+    parts = snake.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def to_snake_case(camel: str) -> str:
+    import re
+    return re.sub(r"([A-Z])", r"_\1", camel).lower().lstrip("_")
+
+
+def _to_pascal_case(snake: str) -> str:
+    return "".join(p.capitalize() for p in snake.split("_"))
+
+
+_GQL_TYPE_MAP = {
+    "string": "String",
+    "integer": "Int",
+    "number": "Float",
+    "boolean": "Boolean",
+    "object": "JSON",
+    "array": "JSON",
+}
+
+
+def generate_schema(capabilities: dict[str, CapabilityDeclaration]) -> str:
+    """Generate a complete GraphQL SDL schema from ANIP capabilities."""
+    lines = [
+        'directive @anipSideEffect(type: String!, rollbackWindow: String) on FIELD_DEFINITION',
+        'directive @anipCost(certainty: String!, currency: String, rangeMin: Float, rangeMax: Float) on FIELD_DEFINITION',
+        'directive @anipRequires(capabilities: [String!]!) on FIELD_DEFINITION',
+        'directive @anipScope(scopes: [String!]!) on FIELD_DEFINITION',
+        '',
+        'scalar JSON',
+        '',
+        'type CostActual { financial: FinancialCost, varianceFromEstimate: String }',
+        'type FinancialCost { amount: Float, currency: String }',
+        'type ANIPFailure { type: String!, detail: String!, resolution: Resolution, retry: Boolean! }',
+        'type Resolution { action: String!, requires: String, grantableBy: String }',
+        '',
+    ]
+
+    queries = []
+    mutations = []
+
+    for name, decl in capabilities.items():
+        pascal = _to_pascal_case(name)
+        camel = to_camel_case(name)
+
+        lines.append(f"type {pascal}Result {{ success: Boolean!, result: JSON, costActual: CostActual, failure: ANIPFailure }}")
+
+        args = _build_field_args(decl)
+        directives = _build_directives(decl)
+        field_line = f"  {camel}{args}: {pascal}Result! {directives}"
+
+        se_type = decl.side_effect.type.value if hasattr(decl.side_effect.type, "value") else str(decl.side_effect.type)
+        if se_type == "read":
+            queries.append(field_line)
+        else:
+            mutations.append(field_line)
+
+    lines.append("")
+    if queries:
+        lines.append("type Query {")
+        lines.extend(queries)
+        lines.append("}")
+    if mutations:
+        lines.append("type Mutation {")
+        lines.extend(mutations)
+        lines.append("}")
+
+    return "\n".join(lines)
+
+
+def _build_field_args(decl: CapabilityDeclaration) -> str:
+    if not decl.inputs:
+        return ""
+    args = []
+    for inp in decl.inputs:
+        gql_type = _GQL_TYPE_MAP.get(inp.type, "String")
+        if inp.required:
+            gql_type += "!"
+        args.append(f"{to_camel_case(inp.name)}: {gql_type}")
+    return "(" + ", ".join(args) + ")"
+
+
+def _build_directives(decl: CapabilityDeclaration) -> str:
+    parts = []
+    se_type = decl.side_effect.type.value if hasattr(decl.side_effect.type, "value") else str(decl.side_effect.type)
+    rollback = decl.side_effect.rollback_window
+
+    se_dir = f'@anipSideEffect(type: "{se_type}"'
+    if rollback:
+        se_dir += f', rollbackWindow: "{rollback}"'
+    se_dir += ")"
+    parts.append(se_dir)
+
+    if decl.cost:
+        certainty = decl.cost.certainty.value if hasattr(decl.cost.certainty, "value") else str(decl.cost.certainty)
+        cost_dir = f'@anipCost(certainty: "{certainty}"'
+        if decl.cost.financial:
+            financial = decl.cost.financial
+            currency = financial.get("currency") if isinstance(financial, dict) else getattr(financial, "currency", None)
+            if currency:
+                cost_dir += f', currency: "{currency}"'
+        cost_dir += ")"
+        parts.append(cost_dir)
+
+    if decl.requires:
+        cap_names = ", ".join(f'"{r.capability}"' for r in decl.requires)
+        parts.append(f"@anipRequires(capabilities: [{cap_names}])")
+
+    if decl.minimum_scope:
+        scope_vals = ", ".join(f'"{s}"' for s in decl.minimum_scope)
+        parts.append(f"@anipScope(scopes: [{scope_vals}])")
+
+    return " ".join(parts)
+
+
+def build_graphql_response(result: dict[str, Any]) -> dict[str, Any]:
+    """Map ANIP invoke response to GraphQL result shape (camelCase)."""
+    response: dict[str, Any] = {
+        "success": result.get("success", False),
+        "result": result.get("result"),
+        "costActual": None,
+        "failure": None,
+    }
+
+    cost_actual = result.get("cost_actual")
+    if cost_actual:
+        response["costActual"] = {
+            "financial": cost_actual.get("financial"),
+            "varianceFromEstimate": cost_actual.get("variance_from_estimate"),
+        }
+
+    failure = result.get("failure")
+    if failure:
+        resolution = failure.get("resolution")
+        response["failure"] = {
+            "type": failure.get("type", "unknown"),
+            "detail": failure.get("detail", ""),
+            "resolution": {
+                "action": resolution.get("action", ""),
+                "requires": resolution.get("requires"),
+                "grantableBy": resolution.get("grantable_by"),
+            } if resolution else None,
+            "retry": failure.get("retry", False),
+        }
+
+    return response

anip_graphql-0.11.0/src/anip_graphql.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: anip-graphql
+Version: 0.11.0
+Summary: ANIP GraphQL bindings — expose ANIPService capabilities via GraphQL
+Author-email: ANIP Protocol <team@anip.dev>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/anip-protocol/anip
+Keywords: anip,agent,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: anip-service==0.11.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: ariadne>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"

anip_graphql-0.11.0/src/anip_graphql.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/anip_graphql/__init__.py
+src/anip_graphql/routes.py
+src/anip_graphql/translation.py
+src/anip_graphql.egg-info/PKG-INFO
+src/anip_graphql.egg-info/SOURCES.txt
+src/anip_graphql.egg-info/dependency_links.txt
+src/anip_graphql.egg-info/requires.txt
+src/anip_graphql.egg-info/top_level.txt
+tests/test_graphql.py

anip_graphql-0.11.0/src/anip_graphql.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

anip_graphql-0.11.0/src/anip_graphql.egg-info/requires.txt

@@ -0,0 +1,7 @@
+anip-service==0.11.0
+fastapi>=0.115.0
+ariadne>=0.24.0
+
+[dev]
+pytest>=8.0
+httpx>=0.27.0

anip_graphql-0.11.0/src/anip_graphql.egg-info/top_level.txt

@@ -0,0 +1 @@
+anip_graphql

anip_graphql-0.11.0/tests/test_graphql.py

@@ -0,0 +1,172 @@
+"""Tests for the anip-graphql package."""
+import pytest
+
+from anip_core.models import (
+    CapabilityDeclaration, CapabilityInput, CapabilityOutput,
+    SideEffect, SideEffectType,
+)
+from anip_graphql.translation import (
+    generate_schema, to_camel_case, to_snake_case, build_graphql_response,
+)
+
+GREET_DECL = CapabilityDeclaration(
+    name="greet",
+    description="Say hello",
+    inputs=[CapabilityInput(name="name", type="string", required=True, description="Who")],
+    output=CapabilityOutput(type="object", fields=["message"]),
+    side_effect=SideEffect(type=SideEffectType.READ, rollback_window="not_applicable"),
+    minimum_scope=["greet"],
+)
+
+BOOK_DECL = CapabilityDeclaration(
+    name="book_item",
+    description="Book something",
+    inputs=[CapabilityInput(name="item_name", type="string", required=True, description="What")],
+    output=CapabilityOutput(type="object", fields=["booking_id"]),
+    side_effect=SideEffect(type=SideEffectType.IRREVERSIBLE, rollback_window="none"),
+    minimum_scope=["book"],
+)
+
+
+class TestCaseConversion:
+    def test_to_camel_case(self):
+        assert to_camel_case("search_flights") == "searchFlights"
+        assert to_camel_case("book") == "book"
+
+    def test_to_snake_case(self):
+        assert to_snake_case("searchFlights") == "search_flights"
+        assert to_snake_case("itemName") == "item_name"
+
+
+class TestSDLGeneration:
+    def test_generates_query_for_read(self):
+        sdl = generate_schema({"greet": GREET_DECL})
+        assert "type Query" in sdl
+        assert "greet(name: String!): GreetResult!" in sdl
+
+    def test_generates_mutation_for_irreversible(self):
+        sdl = generate_schema({"book_item": BOOK_DECL})
+        assert "type Mutation" in sdl
+        assert "bookItem(itemName: String!): BookItemResult!" in sdl
+
+    def test_includes_directives(self):
+        sdl = generate_schema({"greet": GREET_DECL})
+        assert "@anipSideEffect" in sdl
+        assert "@anipScope" in sdl
+
+    def test_includes_shared_types(self):
+        sdl = generate_schema({"greet": GREET_DECL})
+        assert "type ANIPFailure" in sdl
+        assert "scalar JSON" in sdl
+
+
+class TestResponseMapping:
+    def test_success_response(self):
+        result = build_graphql_response({"success": True, "result": {"message": "Hi"}})
+        assert result["success"] is True
+        assert result["result"]["message"] == "Hi"
+
+    def test_failure_response(self):
+        result = build_graphql_response({
+            "success": False,
+            "failure": {
+                "type": "scope_insufficient",
+                "detail": "Missing scope",
+                "resolution": {"action": "request_scope", "grantable_by": "admin"},
+                "retry": False,
+            },
+        })
+        assert result["success"] is False
+        assert result["failure"]["type"] == "scope_insufficient"
+        assert result["failure"]["resolution"]["grantableBy"] == "admin"
+
+    def test_cost_actual_mapping(self):
+        result = build_graphql_response({
+            "success": True,
+            "result": {},
+            "cost_actual": {
+                "financial": {"amount": 100, "currency": "USD"},
+                "variance_from_estimate": "-5%",
+            },
+        })
+        assert result["costActual"]["financial"]["amount"] == 100
+        assert result["costActual"]["varianceFromEstimate"] == "-5%"
+
+
+class TestMountIntegration:
+    """Integration tests using a real ANIPService + FastAPI TestClient."""
+
+    API_KEY = "test-key"
+
+    @pytest.fixture
+    def client(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+        from anip_service import ANIPService, Capability
+        from anip_fastapi import mount_anip
+        from anip_graphql import mount_anip_graphql
+
+        service = ANIPService(
+            service_id="test-graphql",
+            capabilities=[
+                Capability(
+                    declaration=GREET_DECL,
+                    handler=lambda ctx, params: {"message": f"Hello, {params['name']}!"},
+                ),
+                Capability(
+                    declaration=BOOK_DECL,
+                    handler=lambda ctx, params: {"booking_id": "BK-001"},
+                ),
+            ],
+            authenticate=lambda bearer: "test-agent" if bearer == self.API_KEY else None,
+        )
+        app = FastAPI()
+        mount_anip(app, service)          # owns lifecycle via app hooks
+        mount_anip_graphql(app, service)  # adds GraphQL routes only
+        return TestClient(app)
+
+    def test_query_read_capability(self, client):
+        resp = client.post(
+            "/graphql",
+            json={"query": '{ greet(name: "World") { success result } }'},
+            headers={"Authorization": f"Bearer {self.API_KEY}"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["data"]["greet"]["success"] is True
+        assert data["data"]["greet"]["result"]["message"] == "Hello, World!"
+
+    def test_mutation_write_capability(self, client):
+        resp = client.post(
+            "/graphql",
+            json={"query": 'mutation { bookItem(itemName: "x") { success result } }'},
+            headers={"Authorization": f"Bearer {self.API_KEY}"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["data"]["bookItem"]["success"] is True
+
+    def test_query_with_invalid_jwt_returns_invalid_token(self, client):
+        resp = client.post(
+            "/graphql",
+            json={"query": '{ greet(name: "World") { success failure { type } } }'},
+            headers={"Authorization": "Bearer garbage-not-a-jwt"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["data"]["greet"]["success"] is False
+        assert data["data"]["greet"]["failure"]["type"] == "invalid_token"
+
+    def test_query_without_auth_returns_failure(self, client):
+        resp = client.post(
+            "/graphql",
+            json={"query": '{ greet(name: "World") { success failure { type } } }'},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["data"]["greet"]["success"] is False
+        assert data["data"]["greet"]["failure"]["type"] == "authentication_required"
+
+    def test_schema_endpoint(self, client):
+        resp = client.get("/schema.graphql")
+        assert resp.status_code == 200
+        assert "type Query" in resp.text