2026-09-24 01:57:25 +00:00
package llm
import (
"context"
"encoding/json"
2026-09-24 17:07:01 +00:00
"errors"
2026-09-24 01:57:25 +00:00
"fmt"
2026-09-24 17:07:01 +00:00
"sync"
2026-09-24 01:57:25 +00:00
"time"
2026-11-10 16:50:29 +00:00
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
2026-10-11 01:40:38 +00:00
"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"
2026-11-10 16:50:29 +00:00
pk "go.maximumdirect.net/promptkit"
2026-09-24 01:57:25 +00:00
)
// CallHooks receive one logical start and finish record and the execution
2026-11-16 14:27:54 +00:00
// events associated with the call.
2026-09-24 01:57:25 +00:00
type CallHooks struct {
2026-09-24 02:23:57 +00:00
OnCall func ( structuredoutput . CallRecord )
OnEvent pk . ExecutionObserver
OnEventWithCall func ( uint64 , structuredoutput . DiagnosticContext , pk . ExecutionEvent )
2026-11-17 04:17:24 +00:00
// OnProgress runs before and after the engine's timed operation. A nil
// count marks the start. A completion may have unknown execution counts.
OnProgress func ( structuredoutput . DiagnosticContext , * outcomes . ExecutionCounts , error )
2026-09-24 01:57:25 +00:00
}
type RoleClient struct {
2026-11-16 03:37:29 +00:00
runtime * Runtime
role string
profileID string
settings config . LLM
hooks CallHooks
2026-09-24 01:57:25 +00:00
}
var _ structuredoutput . Client = ( * RoleClient ) ( nil )
2026-11-10 16:50:29 +00:00
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" )
2026-09-24 01:57:25 +00:00
}
2026-11-10 16:50:29 +00:00
if profileID == "" {
return nil , fmt . Errorf ( "profile selection is required" )
}
return & RoleClient { runtime : r , role : role , profileID : profileID , settings : settings , hooks : hooks } , nil
2026-09-24 01:57:25 +00:00
}
2026-11-15 01:25:55 +00:00
type pendingCall struct {
2026-11-16 14:27:54 +00:00
request pk . RunRequest
once sync . Once
complete func ( * pk . RunResult , error ) ( structuredoutput . Response , error )
response structuredoutput . Response
err error
}
func ( p * pendingCall ) finish ( result * pk . RunResult , err error ) ( structuredoutput . Response , error ) {
p . once . Do ( func ( ) {
p . response , p . err = p . complete ( result , err )
} )
return p . response , p . err
2026-11-15 01:25:55 +00:00
}
func ( c * RoleClient ) prepareCall ( parent context . Context , req structuredoutput . Request , out any , observer pk . ExecutionObserver ) ( * pendingCall , error ) {
2026-11-16 14:27:54 +00:00
var mu sync . Mutex
2026-09-24 17:07:01 +00:00
var terminal pk . ExecutionEvent
2026-11-16 14:27:54 +00:00
var terminalAvailable bool
var prepared * structuredoutput . PreparedSnapshot
2026-11-16 15:08:02 +00:00
var prompt structuredoutput . PromptMetadata
2026-11-10 20:48:32 +00:00
var record structuredoutput . CallRecord
2026-11-17 04:17:24 +00:00
progressContext := req . Context
progressContext . Role = c . role
if progress := c . hooks . OnProgress ; progress != nil {
progress ( progressContext , nil , nil )
}
2026-11-10 20:48:32 +00:00
if c . hooks . OnCall != nil || c . hooks . OnEventWithCall != nil {
record . CallID = c . runtime . nextCallID . Add ( 1 )
2026-11-11 04:18:05 +00:00
record . RequestedPromptID = req . PromptID
2026-11-10 20:48:32 +00:00
record . Context = copyContext ( req . Context )
record . Context . Role = c . role
2026-09-24 01:57:25 +00:00
}
2026-11-10 20:48:32 +00:00
if onCall := c . hooks . OnCall ; onCall != nil {
record . Started = time . Now ( ) . UTC ( )
record . Prompt = structuredoutput . PromptMetadata { PromptID : req . PromptID , ProfileID : c . profileID }
onCall ( record )
2026-11-16 14:27:54 +00:00
}
call := & pendingCall { complete : func ( result * pk . RunResult , runErr error ) ( structuredoutput . Response , error ) {
var response structuredoutput . Response
mu . 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
}
}
2026-11-16 15:08:02 +00:00
response . Prepared = prepared
response . Prompt = prompt
response . Model = prompt . Model
2026-11-16 14:27:54 +00:00
mu . Unlock ( )
if result != nil {
2026-11-16 15:08:02 +00:00
if req . CaptureDiagnostics {
response . FinalContent = result . RawOutput
}
2026-11-16 14:27:54 +00:00
response . Model = result . ModelName
}
err := c . finishResponse ( parent , & response , result , runErr , out )
if onCall := c . hooks . OnCall ; onCall != nil {
2026-11-16 15:08:02 +00:00
if response . Prompt . PromptID != "" {
2026-11-16 14:27:54 +00:00
record . Prompt = response . Prompt
}
2026-11-10 20:48:32 +00:00
record . Finished = time . Now ( ) . UTC ( )
if err != nil {
2026-11-16 14:27:54 +00:00
record . Failure = structuredoutput . FailureRuntime
if structuredoutput . IsMalformedError ( err ) {
2026-11-10 20:48:32 +00:00
record . Failure = structuredoutput . FailureMalformedOutput
}
2026-09-24 01:57:25 +00:00
}
2026-11-10 20:48:32 +00:00
onCall ( record )
2026-11-15 01:25:55 +00:00
}
2026-11-17 04:17:24 +00:00
if progress := c . hooks . OnProgress ; progress != nil {
progress ( progressContext , & response . Execution , err )
}
2026-11-16 14:27:54 +00:00
return response , err
} }
fail := func ( err error ) ( * pendingCall , error ) {
_ , err = call . finish ( nil , err )
return call , err
2026-11-15 01:25:55 +00:00
}
2026-11-16 14:27:54 +00:00
if err := parent . Err ( ) ; err != nil {
return fail ( err )
2026-09-24 17:07:01 +00:00
}
2026-11-16 14:27:54 +00:00
if err := validateOutputTarget ( out ) ; err != nil {
2026-11-15 01:25:55 +00:00
return fail ( & structuredoutput . Failure { Class : structuredoutput . FailureFatal , Reason : outcomes . ReasonSetupFailure , Message : "invalid structured output target" , Cause : err } )
2026-09-24 01:57:25 +00:00
}
2026-11-16 14:27:54 +00:00
contract , err := OutputContract ( req . Schema , c . settings . RepairAttempts )
if err != nil {
return fail ( & structuredoutput . Failure { Class : structuredoutput . FailureFatal , Reason : outcomes . ReasonSetupFailure , Message : "unknown structured response schema" , Cause : err } )
2026-09-24 01:57:25 +00:00
}
2026-11-16 14:27:54 +00:00
call . request = pk . RunRequest {
PromptID : req . PromptID , ProfileID : c . profileID , Vars : prompts . ProcessingVariables ( req . Variables ) ,
2026-11-16 14:36:07 +00:00
CaptureExchange : req . CaptureExchange ,
2026-11-16 14:27:54 +00:00
TransientRetries : & c . settings . TransientRetries , OperationTimeout : c . settings . OperationTimeout ,
Validation : contract ,
2026-11-15 01:25:55 +00:00
Observer : pk . ComposeObservers ( observer , func ( event pk . ExecutionEvent ) {
2026-09-24 17:07:01 +00:00
if event . Kind == pk . ExecutionFinished {
2026-11-16 14:27:54 +00:00
mu . Lock ( )
2026-09-24 17:07:01 +00:00
terminal = event
terminalAvailable = true
2026-11-16 14:27:54 +00:00
mu . Unlock ( )
2026-09-24 17:07:01 +00:00
}
2026-09-24 02:23:57 +00:00
if c . hooks . OnEventWithCall != nil {
c . hooks . OnEventWithCall ( record . CallID , record . Context , event )
}
2026-11-15 01:25:55 +00:00
} ) ,
2026-11-16 15:08:02 +00:00
}
if req . CaptureDiagnostics || c . hooks . OnCall != nil {
call . request . OnPrepared = func ( _ context . Context , details pk . PreparedRun ) {
metadata := promptMetadata ( details )
var snapshot * structuredoutput . PreparedSnapshot
if req . CaptureDiagnostics {
snapshot = & structuredoutput . PreparedSnapshot { Messages : convertMessages ( details . Messages ) , Prompt : metadata }
}
2026-11-16 14:27:54 +00:00
mu . Lock ( )
2026-11-16 15:08:02 +00:00
prepared , prompt = snapshot , metadata
2026-11-16 14:27:54 +00:00
mu . Unlock ( )
2026-11-16 15:08:02 +00:00
}
2026-11-15 01:25:55 +00:00
}
2026-11-16 14:27:54 +00:00
return call , nil
}
2026-11-15 01:25:55 +00:00
2026-11-16 14:27:54 +00:00
func ( c * RoleClient ) finishResponse ( parent context . Context , response * structuredoutput . Response , result * pk . RunResult , runErr error , out any ) error {
if runErr != nil || parent . Err ( ) != nil {
var typed * structuredoutput . Failure
if parent . Err ( ) == nil && errors . As ( runErr , & typed ) {
return runErr
2026-11-15 01:25:55 +00:00
}
2026-11-16 14:27:54 +00:00
failure := classifiedFailure ( parent , runErr , result )
if failure . Reason == outcomes . ReasonSetupFailure && errors . Is ( failure , pk . ErrAPIKeyEnvMissing ) {
failure . Message = fmt . Sprintf ( "structured model setup failed for %s profile %q: %v" , c . role , c . profileID , failure . Cause )
2026-11-11 04:18:05 +00:00
}
2026-11-16 14:27:54 +00:00
return failure
}
if result == nil {
return & structuredoutput . Failure { Class : structuredoutput . FailureFatal , Reason : outcomes . ReasonInternalFailure , Message : "structured model call returned no result" }
}
if ! result . Validation . IsValid {
return classifiedFailure ( parent , nil , result )
}
if decodeErr := json . Unmarshal ( [ ] byte ( result . RawOutput ) , out ) ; decodeErr != nil {
var typeError * json . UnmarshalTypeError
if errors . As ( decodeErr , & typeError ) {
return & structuredoutput . Failure { Class : structuredoutput . FailureRecoverable , Reason : outcomes . ReasonInvalidOutput , Message : "structured output contains an unusable value" , Cause : decodeErr }
2026-11-15 01:25:55 +00:00
}
2026-11-16 14:27:54 +00:00
return & 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 )
return nil
2026-11-15 01:25:55 +00:00
}
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 {
2026-11-16 14:27:54 +00:00
return call . response , err
2026-11-11 04:18:05 +00:00
}
2026-11-15 01:25:55 +00:00
result , err := c . runtime . Engine . Run ( ctx , call . request )
return call . finish ( result , err )
2026-09-24 01:57:25 +00:00
}
2026-11-10 16:50:29 +00:00
// 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
}
2026-09-24 17:07:01 +00:00
// classifiedFailure deliberately checks setup defects before broad PromptKit
// validation/generation wrappers. Provider text is kept only in the typed cause.
2026-11-16 14:27:54 +00:00
func classifiedFailure ( parent context . Context , cause error , result * pk . RunResult ) * structuredoutput . Failure {
2026-09-24 17:07:01 +00:00
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"
2026-11-16 14:27:54 +00:00
if ! errors . Is ( cause , parent . Err ( ) ) {
failure . Cause = errors . Join ( parent . Err ( ) , cause )
}
2026-09-24 17:07:01 +00:00
return failure
}
2026-11-15 01:25:55 +00:00
if errors . Is ( cause , pk . ErrOperationTimeout ) {
failure . Class = structuredoutput . FailureRecoverable
failure . Reason = outcomes . ReasonOperationTimeout
failure . Message = "model operation timed out"
return failure
}
2026-09-24 17:07:01 +00:00
if isSetupFailure ( cause ) {
failure . Reason = outcomes . ReasonSetupFailure
failure . Message = "structured model setup failed"
return failure
}
2026-11-16 14:27:54 +00:00
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 , context . DeadlineExceeded ) {
2026-09-24 17:07:01 +00:00
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 . 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 . 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 )
}
2026-09-24 01:57:25 +00:00
func promptMetadata ( details pk . PreparedRun ) structuredoutput . PromptMetadata {
return structuredoutput . PromptMetadata {
2026-11-10 16:50:29 +00:00
PromptID : details . PromptID ,
2026-09-24 01:57:25 +00:00
DefinitionHash : details . PromptHash , RenderedHash : details . RenderedPromptHash ,
ProfileID : details . SelectedProfileID , BackendID : details . SelectedBackendID ,
Model : details . EffectiveModelParams . Model ,
}
}
2026-11-11 04:18:05 +00:00
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 }
2026-11-11 12:26:27 +00:00
if cache := message . CacheControl ; cache != nil {
result [ i ] . CacheControl = & structuredoutput . CacheControl { Type : string ( cache . Type ) , TTL : cache . TTL }
}
2026-11-11 04:18:05 +00:00
}
return result
}