package llm import ( "context" "encoding/json" "errors" "fmt" "sync" "time" "gitea.maximumdirect.net/eric/audita/v3/internal/core/config" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/responseschema" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/structuredoutput" "gitea.maximumdirect.net/eric/audita/v3/internal/prompts" pk "go.maximumdirect.net/promptkit" ) // CallHooks receive one logical start and finish record and the execution // events for this call. Call records can contain transcript content. type CallHooks struct { OnCall func(structuredoutput.CallRecord) OnEvent pk.ExecutionObserver OnEventWithCall func(uint64, structuredoutput.DiagnosticContext, pk.ExecutionEvent) } type RoleClient struct { runtime *Runtime role string profileID string settings config.LLM hooks CallHooks } var _ structuredoutput.Client = (*RoleClient)(nil) func (r *Runtime) NewRoleClient(role, profileID string, settings config.LLM, hooks CallHooks) (*RoleClient, error) { if r == nil || r.Engine == nil { return nil, fmt.Errorf("LLM engine is unavailable") } if profileID == "" { return nil, fmt.Errorf("profile selection is required") } return &RoleClient{runtime: r, role: role, profileID: profileID, settings: settings, hooks: hooks}, nil } type pendingCall struct { request pk.RunRequest finish func(*pk.RunResult, error) (structuredoutput.Response, error) } func (c *RoleClient) prepareCall(parent context.Context, req structuredoutput.Request, out any, observer pk.ExecutionObserver) (*pendingCall, error) { var response structuredoutput.Response var err error var finishHooks []func() ctx := parent var terminalMu sync.Mutex var terminal pk.ExecutionEvent terminalAvailable := false finishHooks = append(finishHooks, func() { terminalMu.Lock() if terminalAvailable { response.Execution = outcomes.ExecutionCounts{ Available: true, ProviderAttempts: int(terminal.Attempts), TransientRetries: int(terminal.TransientRetries), StructuralRepairs: int(terminal.RepairCalls), RetriesExhausted: terminal.RetriesExhausted, } if terminal.StatusCode != 0 { status := terminal.StatusCode response.Execution.HTTPStatus = &status } } terminalMu.Unlock() }) var record structuredoutput.CallRecord if c.hooks.OnCall != nil || c.hooks.OnEventWithCall != nil { record.CallID = c.runtime.nextCallID.Add(1) record.RequestedPromptID = req.PromptID record.Context = copyContext(req.Context) record.Context.Role = c.role } if onCall := c.hooks.OnCall; onCall != nil { record.Started = time.Now().UTC() record.Prompt = structuredoutput.PromptMetadata{PromptID: req.PromptID, ProfileID: c.profileID} onCall(record) finishHooks = append(finishHooks, func() { record.Finished = time.Now().UTC() if err != nil { var failure *structuredoutput.Failure if errors.As(err, &failure) && failure.Reason == outcomes.ReasonInvalidOutputExhausted { record.Failure = structuredoutput.FailureMalformedOutput } else { record.Failure = structuredoutput.FailureRuntime } } onCall(record) }) } finish := func() { for i := len(finishHooks) - 1; i >= 0; i-- { finishHooks[i]() } } fail := func(failure error) (*pendingCall, error) { err = failure finish() return nil, failure } if parent.Err() != nil { return fail(classifiedFailure(parent, ctx, parent.Err(), nil)) } if err = validateOutputTarget(out); err != nil { return fail(&structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonSetupFailure, Message: "invalid structured output target", Cause: err}) } contract, contractErr := OutputContract(req.Schema, c.settings.RepairAttempts) if contractErr != nil { return fail(&structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonSetupFailure, Message: "unknown structured response schema", Cause: contractErr}) } vars := prompts.ProcessingVariables(req.Variables) var exchange *pk.Exchange if req.ContinueFrom != nil { var ok bool exchange, ok = req.ContinueFrom.State.(*pk.Exchange) if !ok || exchange == nil { return fail(&structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonSetupFailure, Message: "repair exchange is unavailable"}) } } runRequest := pk.RunRequest{ PromptID: req.PromptID, ProfileID: c.profileID, Vars: vars, CaptureExchange: req.CaptureExchange, ContinueFrom: exchange, TransientRetries: &c.settings.TransientRetries, Validation: contract, Observer: pk.ComposeObservers(observer, func(event pk.ExecutionEvent) { if event.Kind == pk.ExecutionFinished { terminalMu.Lock() terminal = event terminalAvailable = true terminalMu.Unlock() } if c.hooks.OnEventWithCall != nil { c.hooks.OnEventWithCall(record.CallID, record.Context, event) } }), } var details pk.PreparedRun capturePrepared := func(_ context.Context, prepared pk.PreparedRun) { details = prepared response.Prompt = promptMetadata(details) record.Prompt = response.Prompt response.Model = details.EffectiveModelParams.Model response.Prepared = preparedSnapshot(details) record.Prepared = response.Prepared } runRequest.OperationTimeout = c.settings.OperationTimeout runRequest.OnPrepared = capturePrepared return &pendingCall{request: runRequest, finish: func(result *pk.RunResult, runErr error) (completed structuredoutput.Response, finalErr error) { defer func() { err = finalErr; finish(); completed = response }() if result != nil { response.FinalContent = result.RawOutput record.FinalContent = result.RawOutput response.Model = result.ModelName response.PromptTokens = result.Usage.PromptTokens response.CompletionTokens = result.Usage.CompletionTokens response.TotalTokens = result.Usage.TotalTokens } if runErr != nil { return response, classifiedFailure(parent, ctx, runErr, result) } if result == nil { return response, &structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonInternalFailure, Message: "structured model call returned no result"} } if !result.Validation.IsValid { return response, classifiedFailure(parent, ctx, nil, result) } if decodeErr := json.Unmarshal([]byte(result.RawOutput), out); decodeErr != nil { var typeError *json.UnmarshalTypeError if errors.As(decodeErr, &typeError) { return response, &structuredoutput.Failure{Class: structuredoutput.FailureRecoverable, Reason: outcomes.ReasonInvalidOutput, Message: "structured output contains an unusable value", Cause: decodeErr} } return response, &structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonInternalFailure, Message: "validated structured output could not be decoded", Cause: decodeErr} } if result.Exchange != nil { response.Exchange = &structuredoutput.Exchange{State: result.Exchange} } response.Content = json.RawMessage(result.RawOutput) response.Provider = "openai-compatible" return response, nil }}, nil } func (c *RoleClient) CompleteStructured(ctx context.Context, req structuredoutput.Request, out any) (structuredoutput.Response, error) { call, err := c.prepareCall(ctx, req, out, c.hooks.OnEvent) if err != nil { return structuredoutput.Response{}, err } result, err := c.runtime.Engine.Run(ctx, call.request) return call.finish(result, err) } // OutputContract maps an Audita domain schema to the native request contract. func OutputContract(schema responseschema.Key, repairs int) (*pk.OutputContract, error) { path, ok := responseschema.AssetPath(schema) if !ok { return nil, fmt.Errorf("schema %q", schema) } return &pk.OutputContract{Format: pk.FormatJSON, ValidationMode: pk.ValidationJSONSchema, SchemaPath: path, RepairAttempts: repairs}, nil } // classifiedFailure deliberately checks setup defects before broad PromptKit // validation/generation wrappers. Provider text is kept only in the typed cause. func classifiedFailure(parent, local context.Context, cause error, result *pk.RunResult) *structuredoutput.Failure { failure := &structuredoutput.Failure{Class: structuredoutput.FailureFatal, Reason: outcomes.ReasonInternalFailure, Message: "structured model call failed", Cause: cause} if parent.Err() != nil { failure.Class = structuredoutput.FailureCanceled failure.Reason = outcomes.ReasonCanceled failure.Message = "processing canceled" failure.Cause = parent.Err() return failure } if errors.Is(cause, pk.ErrOperationTimeout) { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonOperationTimeout failure.Message = "model operation timed out" return failure } if isSetupFailure(cause) { failure.Reason = outcomes.ReasonSetupFailure failure.Message = "structured model setup failed" return failure } if errors.Is(local.Err(), context.DeadlineExceeded) || errors.Is(cause, context.DeadlineExceeded) { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonOperationTimeout failure.Message = "model operation timed out" return failure } if errors.Is(cause, pk.ErrCapacityExceeded) { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonCapacityExceeded failure.Message = "model capacity was unavailable" return failure } if errors.Is(cause, pk.ErrTransport) { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonTransportFailed failure.Message = "model transport failed" return failure } if errors.Is(cause, pk.ErrMalformedResponse) { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonProviderResponseInvalid failure.Message = "model provider response was invalid" return failure } var provider *pk.GenerationError if errors.As(cause, &provider) && provider.StatusCode() != 0 { failure.Class = structuredoutput.FailureRecoverable failure.Reason = outcomes.ReasonProviderFailed failure.Message = "model provider failed" return failure } if result != nil && !result.Validation.IsValid { failure.Class = structuredoutput.FailureRecoverable failure.Kind = structuredoutput.FailureMalformedOutput failure.Reason = outcomes.ReasonInvalidOutputExhausted failure.Message = "structured output remained invalid" return failure } if errors.Is(cause, pk.ErrValidation) { failure.Reason = outcomes.ReasonSetupFailure failure.Message = "structured validation contract failed" } return failure } func isSetupFailure(err error) bool { return errors.Is(err, pk.ErrInvalidConfig) || errors.Is(err, pk.ErrInvalidRequest) || errors.Is(err, pk.ErrPromptNotFound) || errors.Is(err, pk.ErrProfileNotFound) || errors.Is(err, pk.ErrPromptLoad) || errors.Is(err, pk.ErrProfileLoad) || errors.Is(err, pk.ErrArtifactLoad) || errors.Is(err, pk.ErrPromptRender) } func promptMetadata(details pk.PreparedRun) structuredoutput.PromptMetadata { return structuredoutput.PromptMetadata{ PromptID: details.PromptID, DefinitionHash: details.PromptHash, RenderedHash: details.RenderedPromptHash, ProfileID: details.SelectedProfileID, BackendID: details.SelectedBackendID, Model: details.EffectiveModelParams.Model, } } func preparedSnapshot(details pk.PreparedRun) *structuredoutput.PreparedSnapshot { messages := convertMessages(details.Messages) return &structuredoutput.PreparedSnapshot{Messages: messages, Prompt: promptMetadata(details)} } func convertMessages(messages []pk.RenderedMessage) []structuredoutput.Message { result := make([]structuredoutput.Message, len(messages)) for i, message := range messages { result[i] = structuredoutput.Message{Role: string(message.Role), Content: message.Content} if cache := message.CacheControl; cache != nil { result[i].CacheControl = &structuredoutput.CacheControl{Type: string(cache.Type), TTL: cache.TTL} } } return result }