Verktygsschema, validering och felhantering

Ett verktygsschema är ett kontrakt mellan modellen och din kod. Ju striktare kontraktet är, desto färre sätt finns det att bryta mot det.

Fyra saker som gör schemat bra:

1. enum i stället för fri sträng där värdemängden är känd — då kan modellen inte hitta på kategorier.
2. Gränser på tal och längder (minimum, maxLength) — fångar orimliga anrop innan de körs.
3. required och additionalProperties: false — inga saknade eller påhittade fält.
4. Beskrivningar som modellen läser — description är inte dokumentation för människor, det är en del av prompten.

Modellen ser bara schemat. Ett fält som heter q utan beskrivning kommer att användas fel.

from typing import Literal
from pydantic import BaseModel, Field, ValidationError
import json

class SokArenden(BaseModel):
    """Sök ärenden i supportsystemet. Returnerar högst 50 träffar."""
    status: Literal["oppen", "stangd", "vantar"] = Field(description="Ärendets aktuella status")
    aldre_an_dagar: int | None = Field(default=None, ge=0, le=365,
                                       description="Endast ärenden äldre än detta antal dagar")
    fritext: str | None = Field(default=None, max_length=200,
                                description="Sökord i ärendets titel eller beskrivning")
    model_config = {"extra": "forbid"}          # additionalProperties: false

VERKTYG = {"sok_arenden": (SokArenden, sok_arenden_impl)}

def spec():
    return [{"type": "function", "function": {
                "name": namn,
                "description": (modell.__doc__ or "").strip(),
                "parameters": modell.model_json_schema()}}
            for namn, (modell, _) in VERKTYG.items()]

def kor(namn: str, argument: str) -> dict:
    if namn not in VERKTYG:
        return {"error": f"okänt verktyg '{namn}'. Tillgängliga: {sorted(VERKTYG)}"}
    schema, fn = VERKTYG[namn]
    try:
        args = schema.model_validate_json(argument)
    except ValidationError as e:
        fel = [{"fält": ".".join(str(x) for x in f["loc"]), "problem": f["msg"]} for f in e.errors()]
        return {"error": "ogiltiga argument", "detaljer": fel}      # strukturerat → modellen kan rätta
    except json.JSONDecodeError as e:
        return {"error": f"argumenten är inte giltig JSON: {e}"}
    try:
        return fn(args)
    except Exception as e:
        return {"error": f"verktyget misslyckades: {type(e).__name__}"}   # läck aldrig stack trace

Felmeddelandet är en del av gränssnittet. «ogiltiga argument» hjälper ingen; {"fält": "aldre_an_dagar", "problem": "Input should be less than or equal to 365"} gör att modellen rättar sig i nästa varv. Skicka tillbaka felet som verktygsresultat i stället för att avbryta.