Documentation
¶
Overview ¶
Package embed exposes Chronos as an in-process Go library. Use this package when you want to embed Chronos directly into your application (an agent runtime, a memory layer, a test harness) instead of running it as a CLI or HTTP service.
A typical wiring:
eng, err := embed.New(embed.WithStorage("sqlite:///app.db?namespace=mychronos"))
if err != nil { return err }
defer eng.Close()
state := chronos.EntityState{
EntityID: someEntityID,
ScopeID: someScopeID,
Timestamp: time.Now(),
Features: []float64{42, 0.85, 1.0},
}
if err := eng.Process(ctx, state); err != nil { return err }
signals, err := eng.Detect(ctx, []uuid.UUID{someScopeID})
// or:
signals, err = eng.Query(ctx, embed.QueryOpts{ScopeID: someScopeID})
The CLI (`cmd/chronos`) and the HTTP server are unaffected by this package; they remain the recommended path for multi-tenant Chronos deployments. This package is for in-process embedding only.
Index ¶
- type Engine
- func (e *Engine) Close() error
- func (e *Engine) Detect(ctx context.Context, scopeIDs []uuid.UUID) ([]chronos.Signal, error)
- func (e *Engine) Process(ctx context.Context, state chronos.EntityState) error
- func (e *Engine) ProcessBatch(ctx context.Context, states []chronos.EntityState) error
- func (e *Engine) Query(ctx context.Context, opts QueryOpts) ([]chronos.Signal, error)
- type Option
- type QueryOpts
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the embeddable in-process Chronos engine. Constructed with New; call Engine.Close when finished to release the storage handle.
Engine methods are safe for concurrent read use (Engine.Query, Engine.Detect without state writes). Writes (Engine.Process, Engine.ProcessBatch) should be serialised per scope to avoid the detector producing duplicate signals from races.
func New ¶
New constructs an Engine from the supplied options. When no WithStorage is supplied the engine boots against an in-process memory store, which is suitable for tests and short-lived demos but not for production data retention.
The returned Engine owns the storage handle and MUST be closed via Engine.Close when finished.
func (*Engine) Close ¶
Close releases the engine's storage handle. Idempotent — safe to call more than once.
func (*Engine) Detect ¶
Detect runs the detector set against the entity states currently stored under each of the supplied scope ids. Detected signals are persisted and returned. Pass an empty slice to skip detection.
func (*Engine) Process ¶
Process persists a single observation. The state is validated and stored via the engine's EntityStateRepository. Detection is NOT run automatically; call Engine.Detect or Engine.Query to surface the signals the new state implies.
func (*Engine) ProcessBatch ¶
ProcessBatch persists a batch of observations atomically (when the underlying provider supports transactions) or sequentially (when it does not). All states are validated before any write.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures New. Construct via the With* helpers.
func WithDetectionConfig ¶
WithDetectionConfig overrides the detector configuration. When unset, config.Default is used. Callers typically tweak individual thresholds rather than replacing the whole config.
func WithDetectors ¶
WithDetectors overrides the detector set. Pass an empty slice to disable detection entirely (the engine becomes a passive event log). When unset, detect.DefaultDetectors is used.
func WithLogger ¶
WithLogger overrides the slog.Logger the engine uses for internal diagnostics. Defaults to a discard logger so the embeddable surface is silent unless the host opts in.
func WithParallelDetectors ¶
func WithParallelDetectors() Option
WithParallelDetectors enables parallel detector execution. Detectors are pure functions of their inputs; enabling this is safe and trades CPU for wall-clock latency on multi-detector scopes.
func WithStorage ¶
WithStorage overrides the storage DSN. Schemes registered in internal/store (memory, sqlite, postgres, mysql, libsql) are supported when their provider package is blank-imported by the consuming program. The default is "memory://?namespace=chronos".
type QueryOpts ¶
type QueryOpts struct {
ScopeID uuid.UUID
ScopeIDs []uuid.UUID
Series *uuid.UUID
Pattern *chronos.PatternType
Since *time.Time
Until *time.Time
MinConfidence *float64
Limit int
}
QueryOpts filters a Engine.Query result. At least one of ScopeID or ScopeIDs should be set for performance; unscoped queries scan the whole signal table.
Source Files