# Copyright The DeviceChain Authors
# SPDX-License-Identifier: Apache-2.0

# ---------------------------------------------------------------------------
# DeviceChain GraphQL schema: ai-inference — service plane.
#
#   Endpoint   https://<your-host>/api/ai-inference/graphql
#   Authorize  service token
#   All areas  https://docs.devicechain.io/schema/index.json
#
# Generated from backend/services/ai-inference/graphql/schema.graphql.
# Introspection is disabled by default on a DeviceChain instance, so this file
# is how to read the API without deploying one.
# ---------------------------------------------------------------------------

#
# AI Inference GraphQL Schema — the DATA plane
#
# This is the tenant-facing surface, and it is deliberately tiny: one call, made on
# behalf of a tenant's NL→rule authoring request. Everything an OPERATOR does —
# registering providers, their write-only API keys, granting them to tiers, smoke-
# testing an endpoint — lives on the instance-scoped admin plane instead
# (admin_schema.graphql, served at /admin/graphql behind an identity token).
#
# The split is the correction. The AIProvider list was always an
# instance-scoped, operator-managed resource, but it was served HERE, on the plane
# that authenticates tenant access tokens — so the only way to reach it was from
# inside a tenant, and the console put the screen there. A tenant does not
# administer providers; it only CONSENTS to external routing (the per-tenant
# ai_external_enabled flag on user-management).
#
# Descriptions: a """string""" above an element is its PUBLIC description — served by
# introspection, read by every GraphQL tool, published on the docs site — and may not
# cite a decision record. A # comment is a maintainer note.

"""Identity of the service answering the request."""
# Static service identity — the deployed functional area (non-sensitive).
type ServiceInfo {
    """The functional area this service serves; for this service, the AI inference area."""
    area: String!
}

"""
A prompt to send to the model. The output-token limit, the endpoint and the call
timeout are fixed by the server and cannot be set by the caller.
"""
# An inference request: the user prompt plus an optional system prompt. The
# output-token cap, the provider endpoint, and the call timeout are server-side (the
# fail-closed service config + the resolved provider row), never caller-supplied.
input InferenceRequest {
    """The user prompt. Required, and must not be blank. The prompt and system prompt together may not exceed 128 KiB unless the operator configured a different limit."""
    # The user prompt (required).
    prompt: String!
    """Optional system prompt (instructions or persona) sent ahead of the prompt."""
    # An optional system prompt (instructions/persona).
    system: String
}

"""
The model's answer to an inference request.
"""
# The result of an inference call: the candidate the provider produced (returned
# verbatim — validated downstream by the deterministic rule compiler, not trusted
# here), the model that answered, and the provider token that served it.
type InferenceResult {
    """The model's text output, returned as produced. It is a proposal only: nothing has validated it."""
    candidate: String!
    """Identifier of the model that answered, as reported by the provider."""
    model: String!
    """Token of the registered provider that served the call."""
    provider: String!
}

type Query {
    """Identifies the service answering. Requires no specific authority."""
    # Non-sensitive service identity (the deployed functional area).
    aiInferenceInfo: ServiceInfo!
}

type Mutation {
    """
    Drafts a detection rule: sends the prompt to the model the calling tenant has been
    assigned for rule drafting, or else its tier's default model, and returns the output
    unvalidated. The tenant comes from the caller's token. The call fails if the tenant's
    tier offers no usable model or the provider has no API key (the error is only
    "inference is unavailable", whatever the cause), if the tenant has not opted in to
    external AI routing (a distinct error), if the tenant is over its inference rate limit
    (a distinct, retryable error), or if the prompt is blank or too large. The function
    cannot be chosen by the caller. Requires ai:infer.
    """
    # Run a prompt through the tenant's DEFAULT model for its NL→rule authoring request.
    # Gated by the least-privilege ai:infer authority; the tenant
    # comes from the caller's token. Fails closed when the tenant's tier offers no model,
    # the provider is disabled, the tenant has not opted in to external routing, or no
    # API key is set. The candidate is validated downstream by the rule compiler.
    inferRuleCandidate(
        """The prompt to send."""
        request: InferenceRequest!
    ): InferenceResult!
}

schema {
    query: Query
    mutation: Mutation
}