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
// events for this call. Call records can contain transcript content.
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-09-24 01:57:25 +00:00
}
type RoleClient struct {
2026-11-10 16:50:29 +00:00
runtime * Runtime
role string
profileID string
settings config . LLM
hooks CallHooks
credentialMu sync . Mutex
credentialNames map [ string ] struct { }
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 {
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
2026-09-24 17:07:01 +00:00
var terminalMu sync . Mutex
var terminal pk . ExecutionEvent
terminalAvailable := false
2026-11-15 01:25:55 +00:00
finishHooks = append ( finishHooks , func ( ) {
2026-09-24 17:07:01 +00:00
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 ( )
2026-11-15 01:25:55 +00:00
} )
2026-11-10 20:48:32 +00:00
var record structuredoutput . CallRecord
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-15 01:25:55 +00:00
finishHooks = append ( finishHooks , func ( ) {
2026-11-10 20:48:32 +00:00
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
}
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
} )
}
finish := func ( ) {
for i := len ( finishHooks ) - 1 ; i >= 0 ; i -- {
finishHooks [ i ] ( )
}
}
fail := func ( failure error ) ( * pendingCall , error ) {
err = failure
finish ( )
return nil , failure
2026-11-10 20:48:32 +00:00
}
2026-09-24 17:07:01 +00:00
if parent . Err ( ) != nil {
2026-11-15 01:25:55 +00:00
return fail ( classifiedFailure ( parent , ctx , parent . Err ( ) , nil ) )
2026-09-24 17:07:01 +00:00
}
2026-09-24 01:57:25 +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-10 16:50:29 +00:00
contract , contractErr := OutputContract ( req . Schema , c . settings . RepairAttempts )
if contractErr != nil {
2026-11-15 01:25:55 +00:00
return fail ( & structuredoutput . Failure { Class : structuredoutput . FailureFatal , Reason : outcomes . ReasonSetupFailure , Message : "unknown structured response schema" , Cause : contractErr } )
2026-09-24 01:57:25 +00:00
}
2026-11-10 16:50:29 +00:00
vars := prompts . WithSharedVariables ( req . Variables )
2026-11-10 18:13:12 +00:00
for name , value := range prompts . SharedVariables ( ) {
vars [ name ] = value
}
2026-11-15 01:25:55 +00:00
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" } )
2026-11-11 04:18:05 +00:00
}
}
2026-11-15 01:25:55 +00:00
runRequest := pk . RunRequest {
PromptID : req . PromptID , ProfileID : c . profileID , Vars : vars ,
CaptureExchange : req . CaptureExchange , ContinueFrom : exchange ,
2026-11-10 16:50:29 +00:00
TransientRetries : & c . settings . TransientRetries ,
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 {
terminalMu . Lock ( )
terminal = event
terminalAvailable = true
terminalMu . Unlock ( )
}
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
} ) ,
}
var details pk . PreparedRun
capturePrepared := func ( _ context . Context , prepared pk . PreparedRun ) {
details = prepared
if name := details . EffectiveModelParams . APIKeyEnv ; name != "" {
c . credentialMu . Lock ( )
if c . credentialNames == nil {
c . credentialNames = make ( map [ string ] struct { } )
}
c . credentialNames [ name ] = struct { } { }
c . credentialMu . Unlock ( )
2026-11-11 04:18:05 +00:00
}
2026-11-15 01:25:55 +00:00
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
2026-11-10 16:50:29 +00:00
}
2026-11-15 01:25:55 +00:00
if runErr != nil {
return response , classifiedFailure ( parent , ctx , runErr , result )
2026-09-24 17:07:01 +00:00
}
2026-11-15 01:25:55 +00:00
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 )
2026-11-11 04:18:05 +00:00
}
2026-11-15 01:25:55 +00:00
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
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.
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
}
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
}
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 )
}
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 ,
}
}
func preparedSnapshot ( details pk . PreparedRun ) * structuredoutput . PreparedSnapshot {
2026-11-15 01:25:55 +00:00
messages := convertMessages ( details . Messages )
2026-09-24 01:57:25 +00:00
return & structuredoutput . PreparedSnapshot { Messages : messages , Prompt : promptMetadata ( details ) }
}
2026-11-10 16:50:29 +00:00
// ConfiguredSecrets supplies artifact redaction with the engine's referenced credentials.
func ( c * RoleClient ) ConfiguredSecrets ( ctx context . Context ) [ ] string {
c . credentialMu . Lock ( )
names := make ( [ ] string , 0 , len ( c . credentialNames ) )
for name := range c . credentialNames {
names = append ( names , name )
}
c . credentialMu . Unlock ( )
return c . runtime . ConfiguredSecrets ( ctx , names ... )
}
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
}