agent

type Altitude int

type BackfillReport struct {
	Entities int // number of distillable entities enumerated
	Rows     int // total source rows seen across all entities
	Built    int // L0 nodes that were (re)summarized and persisted (changed=true)
}

type ChildDigest struct {
	ID      string `json:"id"`
	Kind    string `json:"kind"`
	Summary string `json:"summary"`
}

type Cluster struct {
	ID      string
	Members []string
}

type ClusterInput struct {
	ID      string
	SemHash uint64
	Vector  []float32
}

type Clusterer interface {
	Cluster(ctx context.Context, inputs []ClusterInput, noiseFloor int) ([]Cluster, error)
	NeedsVectors() bool
}

type Config struct {
	K              int                // candidates per channel (default 24)
	Hops           int                // graph expansion depth (default 1)
	VectorDims     int                // expected embedding dims (default 768)
	ChannelWeights map[string]float64 // per-channel RRF weight (default 1.0 each)
	Tokenizer      func([]byte) int   // token estimator (default bytes/4)
	Strict         bool               // fail on any channel error (default false: lenient)
	GraphSeeds     int                // top seeds (vector+search) to expand in the graph channel (default 8)
	GraphReverse   bool               // expand incoming (reverse) edges too; default false
	Write          WritePolicy        // agent write allowlist; empty = no writes
	Altitude       Altitude           // distillation layer to surface (default AltAuto: budget decides)
	CAS            blob.CAS           // content-addressed store for digest summaries (optional; nil = no CAS-backed ops)
}

type ContextItem struct {
	Entity    string          `json:"entity"`
	ID        string          `json:"id"`
	Row       json.RawMessage `json:"row"`
	Score     float64         `json:"score"`
	Source    []string        `json:"source"`
	Tokens    int             `json:"tokens"`
	Bucket    uint64          `json:"bucket,omitempty"` // entity's L0-digest SemHash, for cluster-coverage dedup
	BucketSet bool            `json:"-"`                // true only when Bucket was populated by a successful L0-digest lookup
}

type ContextPack struct {
	Items    []ContextItem `json:"items"`
	Omitted  int           `json:"omitted"`
	Tokens   int           `json:"tokens"`
	Warnings []string      `json:"warnings,omitempty"`
}

type DigestChild struct {
	ID          string `json:"id"`
	Kind        string `json:"kind"`
	Summary     string `json:"summary"`
	ContentHash string `json:"contentHash"`
	SemHash     string `json:"semHash"`
}

type DigestView struct {
	Node     MapLine       `json:"node"`
	Summary  string        `json:"summary"`
	Children []DigestChild `json:"children"`
}

type DistillConfig struct {
	RecipeVersion string // salts ContentHash; bump to invalidate the whole tree
	VectorDims    int
	SemSeed       int64
	ClusterBits   int // top-p SemHash bits used as the cluster bucket key
	NoiseFloor    int // min members for a bucket to become a cluster node
	ProbeRadius   int // multi-probe Hamming radius for cluster membership (0 = single-bucket, today's behavior)
	FailOpenGuard bool
	Budget        int // default L0 summary token budget

	SummarizerInputBudget int              // max child-summary tokens before a node splits (adaptive depth)
	MaxFanIn              int              // max children before a node splits (adaptive depth backstop)
	ClusterSubBits        int              // prefix-bit increment per split level (Δ)
	Tokenizer             func(string) int // summary token counter; nil = whitespace-word default
	Clusterer             Clusterer        // nil = default SimHashClusterer from ClusterBits/ProbeRadius
}

type DistillObserver interface {
	Summarized()     // a Summarize call was made (L0 or internal node)
	ShortCircuited() // a Merkle hash matched — the node was not re-summarized
	NodeBuilt()      // a node summary was persisted (CAS + vector + row)
	GuardBlocked()   // a guard vetoed an ingest or emit (fail-closed drop)
	Split()          // an aggregating node overflowed and was split into intermediate nodes
	Deduped()        // an L0 reused an existing summary via exact source-hash match
	GCed()           // an orphaned adaptive-depth intermediate node was garbage-collected
}

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

type Embedder interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
	Dims() int
}

type Guard interface {
	Guard(ctx context.Context, in GuardInput) (GuardResult, error)
}

type GuardInput struct {
	Stage    GuardStage `json:"stage"`
	TenantID string     `json:"tenantId"`
	Scope    ScopeRef   `json:"scope"`
	Level    int        `json:"level"`
	Text     string     `json:"text"`
}

type GuardResult struct {
	Text    string `json:"text"`
	Blocked bool   `json:"blocked"`
	Reason  string `json:"reason"`
}

type GuardStage int

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

type MapLine struct {
	ID          string `json:"id"`
	Level       int    `json:"level"`
	Kind        string `json:"kind"`
	Scope       string `json:"scope,omitempty"`
	ContentHash string `json:"contentHash"`
	SemHash     string `json:"semHash"`
	Unchanged   bool   `json:"unchanged,omitempty"`
	Summary     string `json:"summary,omitempty"`
}

type MapRequest struct {
	// Scope, when non-empty, restricts the outline to nodes whose scope_id matches
	// plus the tenant root. Empty means include all nodes.
	Scope string `json:"scope,omitempty"`
	// KnownHashes is the caller's local snapshot: map[nodeID]contentHash.
	// Nodes whose ContentHash matches the known value are marked Unchanged=true
	// (Merkle-diff re-grounding — transfer only the diff).
	KnownHashes map[string]string `json:"knownHashes,omitempty"`
}

type RecallRequest struct {
	Query    string      `json:"query"`
	Budget   int         `json:"budget"`
	Entities []string    `json:"entities"`
	K        int         `json:"k"`
	Hops     int         `json:"hops"`
	Filters  query.Where `json:"filters,omitempty"`
	// Altitude selects which layer of the distillation tree surfaces. AltAuto
	// (the zero value) defers to Config.Altitude, which itself defaults to
	// AltAuto: the budget then decides between entities and the tenant digest.
	Altitude Altitude `json:"altitude,omitempty"`
}

type RememberRequest struct {
	Entity          string          `json:"entity"`
	Op              string          `json:"op"` // create|update|upsert|delete
	AggID           string          `json:"aggId,omitempty"`
	Payload         json.RawMessage `json:"payload,omitempty"`
	ExpectedVersion *int64          `json:"expectedVersion,omitempty"`
}

type ResolveMatch struct {
	Node        MapLine `json:"node"`
	HammingBits int     `json:"hammingBits"`
}

type ResolveResult struct {
	Exact *MapLine       `json:"exact,omitempty"`
	Near  []ResolveMatch `json:"near,omitempty"`
}

type RollupReport struct {
	ScopeNodes    int  // scope (L1) nodes (re)summarized this pass
	ClusterNodes  int  // cluster (L1) nodes (re)summarized this pass
	TenantRolled  bool // the tenant (L2) root was (re)summarized this pass
	ShortCircuits int  // internal nodes that matched their Merkle hash (no model call)
}

type ScopeRef struct {
	Name string `json:"name"`
	ID   string `json:"id"`
}

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

type Summarizer interface {
	Summarize(ctx context.Context, in SummaryInput) (string, error)
}

type SummaryInput struct {
	Level    int           `json:"level"`
	Kind     string        `json:"kind"`
	Scope    ScopeRef      `json:"scope"`
	Children []ChildDigest `json:"children"`
	Raw      []byte        `json:"raw"`
	Budget   int           `json:"budget"`
}

type Tool struct {
	Name        string
	Description string
	InputSchema json.RawMessage
	Handler     func(ctx context.Context, args json.RawMessage) (any, error)
}

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

type WriteError struct {
	Code string
	Msg  string
	Err  error
}

type WritePolicy struct {
	Allow map[string][]command.Op
}