Documentation
¶
Overview ¶
Package extension adapts the Cortex engine as a Forge extension.
It implements the forge.Extension interface to integrate Cortex into a Forge application with automatic dependency discovery, route registration, and lifecycle management.
Configuration can be provided programmatically via ExtOption functions or via YAML configuration files under "extensions.cortex" or "cortex" keys.
Index ¶
- Constants
- type Config
- type ExtOption
- func WithBasePath(path string) ExtOption
- func WithConfig(cfg Config) ExtOption
- func WithDashboard(deps cortexcontract.Deps) ExtOption
- func WithDisableMigrate() ExtOption
- func WithDisableRoutes() ExtOption
- func WithEngineOption(opt engine.Option) ExtOption
- func WithExtension(x plugin.Extension) ExtOption
- func WithGroveDatabase(name string) ExtOption
- func WithNexusOptions(opts ...nexusllm.Option) ExtOption
- func WithOptimization(value *optimization.Optimizer) ExtOption
- func WithRequireConfig(require bool) ExtOption
- func WithRoutes(build func(eng *engine.Engine, router forge.Router) RouteSet) ExtOption
- func WithShieldOptions(opts ...shieldsafety.Option) ExtOption
- func WithStore(s store.Store) ExtOption
- func WithWeaveOptions(opts ...weaveknowledge.Option) ExtOption
- func WithoutAutoAdapters() ExtOption
- type Extension
- func (e *Extension) Engine() *engine.Engine
- func (e *Extension) Handler() http.Handler
- func (e *Extension) Health(ctx context.Context) error
- func (e *Extension) Register(fapp forge.App) error
- func (e *Extension) RegisterContractContributor(d *dispatcher.Dispatcher, reg dc.Registry, wreg dc.WardenRegistry) error
- func (e *Extension) RegisterRoutes(router forge.Router) error
- func (e *Extension) Routes() RouteSet
- func (e *Extension) Start(ctx context.Context) error
- func (e *Extension) Stop(ctx context.Context) error
- type RouteSet
Constants ¶
const ExtensionDescription = "Human-emulating AI agent orchestration"
ExtensionDescription is the human-readable description.
const ExtensionName = "cortex"
ExtensionName is the name registered with Forge.
const ExtensionVersion = cortex.Version
ExtensionVersion is the semantic version.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// DisableRoutes prevents HTTP route registration.
DisableRoutes bool `json:"disable_routes" mapstructure:"disable_routes" yaml:"disable_routes"`
// DisableMigrate prevents auto-migration on start.
DisableMigrate bool `json:"disable_migrate" mapstructure:"disable_migrate" yaml:"disable_migrate"`
// BasePath is the URL prefix for cortex routes (default: "/cortex").
BasePath string `json:"base_path" mapstructure:"base_path" yaml:"base_path"`
// DefaultModel is the LLM model to use when none is specified.
DefaultModel string `json:"default_model" mapstructure:"default_model" yaml:"default_model"`
// DefaultMaxSteps is the maximum reasoning steps per run.
DefaultMaxSteps int `json:"default_max_steps" mapstructure:"default_max_steps" yaml:"default_max_steps"`
// DefaultMaxTokens is the maximum tokens per LLM call.
DefaultMaxTokens int `json:"default_max_tokens" mapstructure:"default_max_tokens" yaml:"default_max_tokens"`
// DefaultTemperature is the LLM sampling temperature.
DefaultTemperature float64 `json:"default_temperature" mapstructure:"default_temperature" yaml:"default_temperature"`
// DefaultReasoningLoop is the reasoning loop strategy (e.g., "react").
DefaultReasoningLoop string `json:"default_reasoning_loop" mapstructure:"default_reasoning_loop" yaml:"default_reasoning_loop"`
// ShutdownTimeout bounds Stop: how long it waits for runs in flight to
// finish. Zero takes the default, 30s; a negative value leaves Stop
// bounded only by its ctx.
ShutdownTimeout time.Duration `json:"shutdown_timeout" mapstructure:"shutdown_timeout" yaml:"shutdown_timeout"`
// RunConcurrency caps how many agent runs execute at once in this
// process, applied with engine.WithRunConcurrency. Zero, the default,
// is unlimited. Runs started by the experimental task workers, prepared
// orchestrations and plan replanning are not counted.
RunConcurrency int `json:"run_concurrency" mapstructure:"run_concurrency" yaml:"run_concurrency"`
// GroveDatabase is the name of a grove.DB registered in the DI container.
// When set, the extension resolves this named database and auto-constructs
// the appropriate store based on the driver type (pg/sqlite/mongo).
// When empty and WithGroveDatabase was called, the default (unnamed) DB is used.
GroveDatabase string `json:"grove_database" mapstructure:"grove_database" yaml:"grove_database"`
// RequireConfig requires config to be present in YAML files.
// If true and no config is found, Register returns an error.
RequireConfig bool `json:"-" yaml:"-"`
}
Config holds the Cortex extension configuration. Fields can be set programmatically via ExtOption functions or loaded from YAML configuration files (under "extensions.cortex" or "cortex" keys).
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults.
type ExtOption ¶
type ExtOption func(*Extension)
ExtOption configures the Cortex Forge extension.
func WithBasePath ¶
WithBasePath sets the URL prefix for all cortex routes.
func WithConfig ¶
WithConfig sets the extension configuration.
func WithDashboard ¶
func WithDashboard(deps cortexcontract.Deps) ExtOption
WithDashboard supplies the authenticated scope mapping and durable audit sink. Engine is supplied by the extension after initialization.
func WithDisableMigrate ¶
func WithDisableMigrate() ExtOption
WithDisableMigrate disables auto-migration on start.
func WithDisableRoutes ¶
func WithDisableRoutes() ExtOption
WithDisableRoutes disables HTTP route registration.
func WithEngineOption ¶
WithEngineOption passes an engine option directly.
func WithExtension ¶
WithExtension registers a Cortex extension (lifecycle hooks).
func WithGroveDatabase ¶
WithGroveDatabase sets the name of the grove.DB to resolve from the DI container. The extension will auto-construct the appropriate store backend (postgres/sqlite/mongo) based on the grove driver type. Pass an empty string to use the default (unnamed) grove.DB.
func WithNexusOptions ¶ added in v1.10.3
WithNexusOptions configures the nexus adapter the extension wires in when it finds a nexus gateway in the container: nexusllm.WithTenant to map a scope to its nexus tenant, nexusllm.WithProvider, WithMetadata and WithSamplingUnsupported. The adapter keeps its place in the option order, so an engine.WithLLM passed with WithEngineOption still replaces it, and WithoutAutoAdapters still leaves it out.
func WithOptimization ¶
func WithOptimization(value *optimization.Optimizer) ExtOption
WithOptimization supplies the dashboard's operator service. Worker scope enumeration and shutdown remain with the host that owns the optimizer. This option takes precedence over the service supplied through WithDashboard.
func WithRequireConfig ¶
WithRequireConfig requires config to be present in YAML files. If true and no config is found, Register returns an error.
func WithRoutes ¶
WithRoutes mounts an HTTP surface on the extension.
The REST handlers live in github.com/xraph/cortex/api, a separate module, so nothing here forces a host to compile them in. Pass this when you want them:
extension.New(
extension.WithRoutes(func(eng *engine.Engine, r forge.Router) extension.RouteSet {
return api.New(eng, r)
}),
)
Leave it out and the extension registers no routes, Routes returns nil and Handler answers 404. The engine, the dashboard and the DI wiring are unaffected either way.
func WithShieldOptions ¶ added in v1.10.3
func WithShieldOptions(opts ...shieldsafety.Option) ExtOption
WithShieldOptions configures the shield adapter the extension wires in when it finds a shield engine in the container: shieldsafety.WithTenant to map a scope to its shield tenant, shieldsafety.WithApp to name the shield app, and shieldsafety.WithUntrustedSources. The adapter keeps its place in the option order, so an engine.WithSafety or engine.WithPublicationGate passed with WithEngineOption still replaces the matching half of it, and WithoutAutoAdapters still leaves it out.
func WithStore ¶
WithStore sets the composite store. It wins over any grove database in the container, and the extension then skips discovering a default one.
func WithWeaveOptions ¶ added in v1.10.3
func WithWeaveOptions(opts ...weaveknowledge.Option) ExtOption
WithWeaveOptions configures the weave adapter the extension wires in when it finds a weave engine in the container: weaveknowledge.WithTenant to map a scope to its weave tenant, and weaveknowledge.WithShared to add read-only collections every run may search. The adapter keeps its place in the option order, so an engine.WithKnowledge passed with WithEngineOption still replaces it, and WithoutAutoAdapters still leaves it out.
func WithoutAutoAdapters ¶ added in v1.10.3
func WithoutAutoAdapters() ExtOption
WithoutAutoAdapters stops the extension from discovering nexus, shield, weave and sentinel in the DI container. Without it, each one found is wired into the engine: nexus as the model client, shield as the safety scanner and the publication gate, weave as the knowledge provider and sentinel as an extension. Use it when the host wires those itself, or wants none of them.
type Extension ¶
type Extension struct {
*forge.BaseExtension
// contains filtered or unexported fields
}
Extension adapts Cortex as a Forge extension.
func (*Extension) Engine ¶
Engine returns the underlying Cortex engine. This is nil until Register is called.
func (*Extension) Handler ¶
Handler returns the HTTP handler for all API routes. Convenience for standalone use outside Forge.
func (*Extension) Health ¶
Health implements forge.Extension.
func (*Extension) Register ¶
Register implements forge.Extension. It loads configuration, initializes the engine, and registers it in the DI container.
func (*Extension) RegisterContractContributor ¶
func (e *Extension) RegisterContractContributor(d *dispatcher.Dispatcher, reg dc.Registry, wreg dc.WardenRegistry) error
func (*Extension) RegisterRoutes ¶
RegisterRoutes registers all Cortex API routes into a Forge router.
func (*Extension) Routes ¶
Routes returns the mounted HTTP surface, or nil when the extension was built without one. Nil is the ordinary case for a host that wants the engine and the dashboard and no REST API.
func (*Extension) Stop ¶
Stop gracefully shuts down the Cortex engine. It waits for runs in flight for at most shutdown_timeout (when positive), or until ctx ends, whichever comes first. If the wait runs out, Stop returns an error matching context.DeadlineExceeded and leaves the extension started; calling Stop again completes the shutdown.
Source Files
Directories