Documentation
¶
Overview ¶
Package promptlayer assembles the prompt subsystem behind one Handle: the Postgres-backed prompt store, the file-based tuning prompt manager, the name-keyed prompt-metadata registry (promptInfos), and every behavior that registers, serves, and manages prompts — the static/workflow/database registration path, the per-viewer dynamic-serving path behind the prompts/list visibility middleware, and the manage_prompt tool.
Construction takes explicit inputs — an optional *sql.DB (nil leaves the store nil; static and workflow prompts still register), the resolved prompts directory, the server name/description, the admin persona, the operator prompt specs, the built-in-prompt disable map, and the toolkit registry — so the subsystem is constructible and testable without a caller assembling it. It imports pkg/prompt, pkg/tuning, pkg/registry, pkg/embedding, pkg/middleware, pkg/portal, and the MCP SDK, never the platform package.
The MCP server is NOT captured at construction: the store and metadata must exist early (other subsystems read the store before the server is created), but the AddPrompt/AddTool registration happens later, so RegisterPlatformPrompts and RegisterTool take the *mcp.Server per call. Two collaborators are bound after construction because they are assembled later than the prompt store: the embedding provider (SetEmbedder — powers manage_prompt semantic ranking; nil falls back to lexical) and the portal share lister (SetShareStore — resolves prompts shared directly with a caller; nil serves no shared prompts). Both serving paths nil-check their collaborator, so a Handle with neither set still serves global/persona/personal prompts.
Index ¶
- type Config
- type Handle
- func (h *Handle) AllPromptInfos() []registry.PromptInfo
- func (h *Handle) GetByName(ctx context.Context, email string, personas []string, name string, ...) (*mcp.GetPromptResult, bool)
- func (h *Handle) ListVisible(ctx context.Context, email string, personas []string) []*mcp.Prompt
- func (h *Handle) LoadPrompts() error
- func (h *Handle) PromptCreator() *PromptCreatorAdapter
- func (h *Handle) RegisterPlatformPrompts(server *mcp.Server)
- func (h *Handle) RegisterRuntimePrompt(pr *prompt.Prompt)
- func (h *Handle) RegisterTool(server *mcp.Server)
- func (h *Handle) SetEmbedder(e embedding.Provider)
- func (h *Handle) SetListChangedNotifier(n ListChangedNotifier)
- func (h *Handle) SetShareStore(s ShareLister)
- func (h *Handle) Store() prompt.Store
- func (h *Handle) UnregisterRuntimePrompt(name string)
- type ListChangedNotifier
- type PromptArgSpec
- type PromptCreatorAdapter
- type PromptSpec
- type ShareLister
- type ToolkitRegistry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// DB backs the prompt store; nil leaves the store nil (static and workflow
// prompts still register, but database prompts and manage_prompt are off).
// Ignored when Store is set.
DB *sql.DB
// Store, when non-nil, is used as the prompt store directly instead of
// building a Postgres store from DB. Lets a caller (or a test) supply an
// already-assembled store; production passes DB and leaves this nil.
Store prompt.Store
// PromptsDir is the directory the tuning prompt manager loads file prompts
// from (empty is valid: the manager loads nothing).
PromptsDir string
// ServerName / ServerDescription title and seed the auto-generated
// platform-overview prompt (an empty description skips it).
ServerName string
ServerDescription string
// AdminPersona is the persona name that grants admin authority over prompts
// at every scope; matched against the caller's persona in each command.
AdminPersona string
// OperatorPrompts are the operator-configured static prompts to register.
OperatorPrompts []PromptSpec
// BuiltinPrompts disables named built-in workflow prompts (name → enabled);
// a name mapped to false is skipped. Nil enables every built-in.
BuiltinPrompts map[string]bool
// Registry is the toolkit registry read for capability bullets, workflow
// gating, and toolkit prompt metadata.
Registry ToolkitRegistry
}
Config carries the resolved values the owner needs to assemble the prompt layer. The caller translates its own config into this shape so this package stays free of the platform's config types.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle owns the assembled prompt layer: the prompt store, the tuning prompt manager, and the name-keyed prompt-metadata list, plus the registration, dynamic-serving, and manage_prompt behaviors. Store exposes the backing store the caller surfaces and hands to the search federation; RegisterPlatformPrompts and RegisterTool take the *mcp.Server per call; ListVisible / GetByName are the prompts/list visibility callbacks the caller wires into the middleware chain; AllPromptInfos / RegisterRuntimePrompt / UnregisterRuntimePrompt back the admin and portal prompt REST handlers. All accessors are nil-safe.
func New ¶
New assembles the prompt layer. It always returns a non-nil Handle: prompts are a first-class feature even without a database (static and workflow prompts register and serve), so a no-DB deployment gets a Handle with a nil store and every store-backed path (database prompts, manage_prompt, search) degrades to a no-op. The tuning prompt manager is built here from the configured prompts directory; the caller starts it with LoadPrompts.
func (*Handle) AllPromptInfos ¶
func (h *Handle) AllPromptInfos() []registry.PromptInfo
AllPromptInfos returns all prompt metadata (platform + toolkit), or nil on a nil Handle. Read by the admin and portal prompt REST handlers to surface system prompts.
func (*Handle) GetByName ¶
func (h *Handle) GetByName(ctx context.Context, email string, personas []string, name string, args map[string]string) (*mcp.GetPromptResult, bool)
GetByName resolves a prefixed prompt name to the caller's visible database prompt and renders it for prompts/get. It strips the scope prefix to the bare stored name: personal-/global- are reserved tokens; a persona prefix must be one of the caller's personas, and the target prompt must actually be shared with that persona. Returns (nil, false) when no such visible prompt exists. Wired as the prompts/get visibility callback.
The reserved-prefix branches fall through to persona resolution on a miss: persona names are operator-defined and may literally be "personal" or "global", so a name like "global-report" must still resolve a persona prompt when no global prompt by that bare name exists.
func (*Handle) ListVisible ¶
ListVisible returns the caller's visible database prompts as MCP descriptors with their scope prefix: global-<name> for globals, <persona>-<name> for each persona the caller belongs to, and personal-<name> for the caller's own. A persona prompt shared with several personas appears once per persona the caller is in. Wired as the prompts/list visibility callback.
func (*Handle) LoadPrompts ¶
LoadPrompts loads the file-based tuning prompts from the configured directory. Called once at startup.
func (*Handle) PromptCreator ¶
func (h *Handle) PromptCreator() *PromptCreatorAdapter
PromptCreator returns an adapter satisfying the knowledge toolkit's PromptCreator interface over this handle, or nil on a no-DB deployment (no store to create into).
func (*Handle) RegisterPlatformPrompts ¶
RegisterPlatformPrompts registers platform-level prompts with the given MCP server. It first registers the auto-generated platform overview prompt (if applicable), then operator-configured prompts, then workflow prompts, then database-stored prompts. No-op on a nil Handle.
func (*Handle) RegisterRuntimePrompt ¶
RegisterRuntimePrompt records a prompt's metadata at runtime. Called after create/update operations on the prompt store. No-op on a nil Handle.
func (*Handle) RegisterTool ¶
RegisterTool registers the manage_prompt tool with the given MCP server. No-op on a nil Handle or a no-DB deployment (no store to manage prompts in).
func (*Handle) SetEmbedder ¶
SetEmbedder binds the embedding provider that powers manage_prompt semantic ranking. Called once the provider is assembled; a nil provider (or never calling this) leaves ranking on the lexical fallback.
func (*Handle) SetListChangedNotifier ¶ added in v1.102.0
func (h *Handle) SetListChangedNotifier(n ListChangedNotifier)
SetListChangedNotifier binds the notifier fired after every prompt store write (create, update, delete). Called once the session broadcaster exists, after construction — like SetEmbedder / SetShareStore. Safe to call on a nil Handle. Because the notifying store wraps the backing store at construction and reads the notifier atomically per write, a prompt created before this binding simply does not notify (there are no connected clients yet), and every write after it does.
func (*Handle) SetShareStore ¶
func (h *Handle) SetShareStore(s ShareLister)
SetShareStore binds the portal share lister used to resolve prompts shared directly with a caller. Called once the portal layer exists; a nil lister (or never calling this) serves no shared prompts.
func (*Handle) Store ¶
Store returns the backing prompt store, or nil on a nil Handle or a no-DB deployment. The caller surfaces it and hands it to the search federation.
func (*Handle) UnregisterRuntimePrompt ¶
UnregisterRuntimePrompt removes a database prompt's tracked metadata. It does NOT remove the prompt from the static MCP registry: database prompts are never placed there (see registerDatabasePrompt), so removing by bare name could only ever delete an unrelated built-in/operator/toolkit prompt of the same name. Only the name-keyed metadata entry (global/persona scope) is dropped. No-op on a nil Handle.
type ListChangedNotifier ¶ added in v1.102.0
type ListChangedNotifier interface {
Notify()
}
ListChangedNotifier schedules a debounced prompts/list_changed notification. *listchanged.Notifier satisfies it; the interface keeps this package free of the notifier's transport dependencies. A nil notifier (never bound) makes every write a silent no-op.
type PromptArgSpec ¶
PromptArgSpec is one argument of an operator- or workflow-defined prompt in the caller-neutral shape this package registers from. The caller translates its own config type into this.
type PromptCreatorAdapter ¶
type PromptCreatorAdapter struct {
// contains filtered or unexported fields
}
PromptCreatorAdapter adapts the Handle to the knowledge toolkit's PromptCreator interface (Create + RegisterRuntimePrompt) for the add_prompt change type, without this package importing the knowledge toolkit.
func (*PromptCreatorAdapter) RegisterRuntimePrompt ¶
func (c *PromptCreatorAdapter) RegisterRuntimePrompt(p *prompt.Prompt)
RegisterRuntimePrompt records the prompt's metadata for admin listing.
type PromptSpec ¶
type PromptSpec struct {
Name string
Description string
Content string
Arguments []PromptArgSpec
}
PromptSpec is an operator- or workflow-defined prompt in the caller-neutral shape this package registers from, decoupling the layer from the caller's config types and defaulting rules.
type ShareLister ¶
type ShareLister interface {
}
ShareLister looks up the prompts shared directly with a caller. The portal share store satisfies it; it is bound via SetShareStore once the portal layer exists. A nil lister disables shared-prompt serving.
type ToolkitRegistry ¶
type ToolkitRegistry interface {
GetByKind(kind string) []registry.Toolkit
All() []registry.Toolkit
}
ToolkitRegistry is the read-only slice of the toolkit registry the prompt layer needs: enabled-kind checks for capability bullets and workflow gating, and the full toolkit list to collect prompt metadata from PromptDescriber toolkits. The concrete *registry.Registry satisfies it.
Source Files