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 WithOptimization(value *optimization.Optimizer) ExtOption
- func WithRequireConfig(require bool) ExtOption
- func WithRoutes(build func(eng *engine.Engine, router forge.Router) RouteSet) ExtOption
- func WithStore(s store.Store) 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 is the maximum time to wait for graceful shutdown.
ShutdownTimeout time.Duration `json:"shutdown_timeout" mapstructure:"shutdown_timeout" yaml:"shutdown_timeout"`
// RunConcurrency controls how many agent runs can execute in parallel.
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 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.
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.
Source Files
Directories