maf

type CaptureFailure struct {
	Stage  CaptureStage
	Reason string
	// RunID is the run's ID, once it started.
	RunID *ae.UUID
	Err   error
}

type CaptureStage string

type ContextProvider struct {
	// contains filtered or unexported fields
}

type HoldoutOptions struct {
	// Rate is the share of eligible runs whose block is withheld, from 0 (off, the default) to 1 (every one). NaN, a
	// negative rate or one above 1 is refused by UseAgentExperience.
	Rate float64
	// Salt is mixed into every assignment, so two experiments over the same runs draw different arms;
	// ae.DefaultHoldoutSalt when empty. (Go cannot tell an empty salt from an unset one, so empty means the default
	// here, where .NET and Python refuse an explicitly empty salt.) Changing it re-draws every run.
	Salt string
}

type HoldoutRecordResult struct {
	Outcome       InjectionRecordOutcome
	RunID         ae.UUID
	Arm           ae.HoldoutArm
	ExperienceIDs []ae.UUID
	Err           error
}

type IdentityContext struct {
	Agent   *agent.Agent
	Session *agent.Session
}

type InjectionFailure struct {
	Reason string
	Err    error
}

type InjectionRecordOutcome string

type InjectionRecordResult struct {
	Outcome       InjectionRecordOutcome
	ExperienceIDs []ae.UUID
	Err           error
}

type InjectionResult struct {
	ExperienceIDs  []ae.UUID
	ByteCount      int
	Truncated      bool
	VectorFallback *ae.VectorFallback
	// WithheldExperienceIDs are the records a held-out invocation's block named and did not deliver (contract 1.8):
	// set only in what OnWithheld is told, where ExperienceIDs is empty and ByteCount 0.
	WithheldExperienceIDs []ae.UUID
}

type Options struct {
	// Store is required: the in-memory store (the inmemory module) for development, or the PostgreSQL store.
	Store ae.Store
	// Identity is who every invocation runs for: ae.DevelopmentIdentity for development and tests, or one from your
	// own authentication. Exactly one of Identity and ResolveIdentity is given.
	Identity ae.Identity
	// ResolveIdentity resolves the identity per invocation from your own authentication; nil (with no error) leaves
	// the invocation neither captured nor injected. A development identity it returns is checked every time.
	ResolveIdentity func(ctx context.Context, identity IdentityContext) (*ae.Identity, error)
	// Verify decides from your own facts whether a run is stored (see ae.ToolSucceeded and the others); without it
	// nothing is stored.
	Verify ae.Verifier
	// ClassifyToolResult marks a returned tool call as failed (see ae.ExitCode and ae.HTTPStatus).
	ClassifyToolResult ae.ToolResultClassifier
	// TaskID is the task ID runs are captured under; when empty, the agent's name reduced to an identifier, else
	// DefaultTaskID.
	TaskID string
	// Sanitization is ae.DefaultSanitization() when zero: only allowlisted argument values are kept.
	Sanitization ae.Sanitization
	// BlockOptions are the block's layout and limits (the contract's defaults when zero).
	BlockOptions ae.BlockOptions
	// Environment is the environment runs are recorded under; DefaultEnvironment() when nil.
	Environment *ae.EnvironmentFingerprint
	// PreferredEnvironment is the metadata ranking prefers.
	PreferredEnvironment map[string]string
	// ExcludeModelAuthored leaves model-authored lessons out of the search and the ranking.
	ExcludeModelAuthored bool
	// MessageRole is the injected message's role: message.RoleUser (when empty) or message.RoleSystem.
	MessageRole message.Role
	// DisableInjection captures without injecting.
	DisableInjection bool
	// OnCaptureFailure, OnInjectionFailure, OnInjected, OnFinalized and OnInjectionRecorded are told what happened;
	// each is optional, and a panic in one is recovered and ignored. OnInjectionRecorded is called from the
	// recording's own goroutine.
	OnCaptureFailure    func(CaptureFailure)
	OnInjectionFailure  func(InjectionFailure)
	OnInjected          func(InjectionResult)
	OnFinalized         func(ae.FinalizedExperience)
	OnInjectionRecorded func(InjectionRecordResult)
	// Holdout is the injection holdout (contract 1.8); off when zero.
	Holdout HoldoutOptions
	// OnWithheld is told, for a held-out invocation, what its block withheld (InjectionResult.WithheldExperienceIDs);
	// OnHoldoutRecorded how recording each assignment ended, from the recording's own goroutine. Each is optional, and a
	// panic in one is recovered and ignored.
	OnWithheld        func(InjectionResult)
	OnHoldoutRecorded func(HoldoutRecordResult)
	// Clock is ae.Now when nil.
	Clock func() ae.Instant
	// NewID is ae.NewRandomUUID when nil.
	NewID func() ae.UUID
	// Embedder (contract 1.6) turns text into a vector, for hybrid retrieval and for embedding each stored record.
	// With one, injection runs the text and the vector channel together (a store that is an ae.EmbeddingIndex serves
	// it: the in-memory store, and the PostgreSQL store with pgvector), merges them and ranks as before, and every
	// stored record's summary is embedded in the background. Without one, or when the vector channel fails, the
	// injection answers from text alone and says why (OnVectorFallback, InjectionResult.VectorFallback). The
	// embedder's calls honour ctx, are bounded by VectorTimeout, and at most MaxVectorCalls run at once, abandoned
	// ones included.
	Embedder ae.Embedder
	// MinVectorRelevance, when set (0 to 1), drops vector candidates whose relevance is below it; text candidates
	// never are.
	MinVectorRelevance *float64
	// VectorTimeout bounds the vector channel of one injection in all (embedding the task text, then searching):
	// past it the injection answers from text alone and reports ProviderUnavailable or VectorSearchFailed.
	// DefaultVectorTimeout when 0.
	VectorTimeout time.Duration
	// OnVectorFallback is told, once per injection, why the vector channel did not contribute (NotConfigured,
	// ProviderUnavailable, ModelMismatch, DimensionMismatch, VectorSearchFailed); optional, and a panic in it is
	// recovered and ignored. Its detail never quotes record or vector content.
	OnVectorFallback func(ae.VectorFallback)
	// FinalizationTimeout bounds how long an invocation's end waits for finalization (append, verify, finalize,
	// store), on its own clock, never the caller's context: past it the work is abandoned and reported, and the
	// invocation returns. DefaultFinalizationTimeout when 0.
	FinalizationTimeout time.Duration
	// InjectionRecordTimeout bounds how long recording one injected block may take in the background, all chunks
	// together: past it the write is abandoned and reported InjectionOutcomeUnknown. The invocation never waits for
	// it. DefaultInjectionRecordTimeout when 0.
	InjectionRecordTimeout time.Duration
}