promptkitty

README

Promptkitty

Embedded PromptKit catalog and deterministic prompt assembler for Go.

Promptkitty packages the complete component library from Microsoft PromptKit v0.6.1 into a Go module. It loads no files and makes no network calls at runtime. Applications can browse personas, protocols, formats, taxonomies, templates, and pipelines, then assemble a fully parameterized prompt.

Install

Install the library or standalone CLI:

go get github.com/baldaworks/promptkitty@v0.2.0
go install github.com/baldaworks/promptkitty/cmd/promptkitty@v0.2.0

Assemble a prompt

library, err := promptkitty.New()
if err != nil {
    return err
}

result, err := library.Assemble(promptkitty.AssembleRequest{
    Template: "investigate-bug",
    Params: map[string]string{
        "problem_description": "Parser crashes on empty input",
        "code_context":        "src/parser.c",
        "environment":         "Linux amd64",
    },
})
if err != nil {
    return err
}

fmt.Println(result.Markdown)

Every parameter declared by the selected template must be present. An empty string is an explicit value. Parameter substitution is one-pass and does not reinterpret mustache syntax supplied as input data.

Composition follows PromptKit's semantic layers:

persona → protocols → taxonomies → format → template

Use Persona, AdditionalProtocols, AdditionalTaxonomies, and Format on AssembleRequest to resolve configurable templates or extend their defaults.

Browse the catalog

templates := library.List(promptkitty.Filter{Type: promptkitty.ComponentTemplate})
security := library.Search("security", promptkitty.Filter{})
review, err := library.Show("review-code")
pipelines := library.Pipelines()

The reusable cli package exposes the same command tree for host applications:

cmd := cli.NewCommand(cli.Options{Use: "promptkit"})
host.AddCommand(cmd)

The standalone command supports list, search, show, and assemble:

promptkitty list
promptkitty search security --type template
promptkitty show review-code --json
promptkitty assemble review-code \
  --param code='package main' \
  --param review_focus=correctness \
  --param language=Go \
  --param additional_protocols= \
  --param context='small example'

assemble writes rendered Markdown to stdout by default. Use --output to write a file or --json to receive the complete assembly result.

Updating PromptKit content

The embedded snapshot is pinned by commit and SHA-256 inventory in content/upstream.json. Maintainers update the ref and commit, then run:

go run ./internal/tools/syncpromptkit \
  -lock content/upstream.json \
  -dest content/promptkit \
  -refresh-lock
go generate ./...

Review component and inventory changes together. Runtime builds never contact GitHub.

License

Promptkitty is MIT licensed. Embedded PromptKit content remains under its original MIT license and attribution; see THIRD_PARTY_NOTICES.md.

Documentation

Overview

Package promptkitty provides an embedded PromptKit component catalog and a deterministic prompt assembler.

Index

• type AmbiguousError
  • func (e *AmbiguousError) Error() string
• type AssembleRequest
• type AssembleResult
• type Component
• type ComponentDetail
• type ComponentRef
• type ComponentType
• type Filter
• type Library
  • func New() (*Library, error)
  • func NewFromFS(fsys fs.FS, root string) (*Library, error)
  • func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)
  • func (l *Library) List(filter Filter) []Component
  • func (l *Library) Pipelines() []Pipeline
  • func (l *Library) Search(query string, filter Filter) []Component
  • func (l *Library) Show(name string) (ComponentDetail, error)
  • func (l *Library) Version() string
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type ParametersError
  • func (e *ParametersError) Error() string
• type Pipeline
• type PipelineStage

Types

type AmbiguousError

type AmbiguousError struct {
	Name  string
	Types []ComponentType
}

AmbiguousError reports a name shared by more than one component type.

func (*AmbiguousError) Error

func (e *AmbiguousError) Error() string

type AssembleRequest

type AssembleRequest struct {
	Template             string
	Params               map[string]string
	Persona              string
	AdditionalProtocols  []string
	AdditionalTaxonomies []string
	// Format leaves the template default when nil, omits the format when it
	// points to an empty string, and otherwise replaces the default.
	Format *string
}

AssembleRequest selects a template, supplies every declared parameter, and optionally adjusts its component composition.

type AssembleResult

type AssembleResult struct {
	Markdown   string         `json:"markdown"`
	Template   Component      `json:"template"`
	Components []ComponentRef `json:"components"`
}

AssembleResult is a completely rendered PromptKit prompt. All declared template parameters have been substituted.

type Component

type Component struct {
	Name        string         `json:"name"`
	Type        ComponentType  `json:"type"`
	Category    string         `json:"category,omitempty"`
	Path        string         `json:"path,omitempty"`
	Description string         `json:"description,omitempty"`
	Language    string         `json:"language,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Component is a catalog entry enriched with its Markdown frontmatter. Metadata is a defensive copy and may be inspected by future transports.

type ComponentDetail

type ComponentDetail struct {
	Component

	UsedByTemplates []string `json:"usedByTemplates,omitempty"`
}

ComponentDetail adds reverse template references to a component.

type ComponentRef

type ComponentRef struct {
	Name string        `json:"name"`
	Type ComponentType `json:"type"`
	Path string        `json:"path"`
}

ComponentRef records one component included in an assembled prompt.

type ComponentType

type ComponentType string

ComponentType identifies one PromptKit component layer.

const (
	ComponentPersona  ComponentType = "persona"
	ComponentProtocol ComponentType = "protocol"
	ComponentFormat   ComponentType = "format"
	ComponentTaxonomy ComponentType = "taxonomy"
	ComponentTemplate ComponentType = "template"
)

type Filter

type Filter struct {
	Type     ComponentType
	Category string
	Language string
}

Filter selects catalog components. Empty fields match every component.

type Library

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

Library is an immutable PromptKit catalog and assembler.

func New

func New() (*Library, error)

New loads the pinned embedded PromptKit component library.

func NewFromFS

func NewFromFS(fsys fs.FS, root string) (*Library, error)

NewFromFS loads a PromptKit library rooted at root within fsys. It is useful for tests and callers that maintain a compatible private catalog.

func (*Library) Assemble

func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)

Assemble resolves a template and returns a fully rendered prompt. Mustache examples that are not declared template parameters are ordinary Markdown literals and are preserved verbatim.

func (*Library) List

func (l *Library) List(filter Filter) []Component

List returns matching components in stable type/category/name order.

func (*Library) Pipelines

func (l *Library) Pipelines() []Pipeline

Pipelines returns the manifest's artifact pipelines in stable name order.

func (*Library) Search

func (l *Library) Search(query string, filter Filter) []Component

Search performs a case-insensitive substring search over component names and descriptions, then applies filter.

func (*Library) Show

func (l *Library) Show(name string) (ComponentDetail, error)

Show returns one component and the templates that reference it.

func (*Library) Version

func (l *Library) Version() string

Version returns the version declared by the embedded PromptKit manifest.

type NotFoundError

type NotFoundError struct {
	Type ComponentType
	Name string
}

NotFoundError reports a requested component that is absent from the catalog.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type ParametersError

type ParametersError struct {
	Template string
	Missing  []string
	Unknown  []string
}

ParametersError reports missing or unknown template parameters.

func (*ParametersError) Error

func (e *ParametersError) Error() string

type Pipeline

type Pipeline struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Stages      []PipelineStage `json:"stages"`
}

Pipeline is one named sequence from the embedded PromptKit manifest.

type PipelineStage

type PipelineStage struct {
	Template string `json:"template"`
	Consumes any    `json:"consumes,omitempty"`
	Produces any    `json:"produces,omitempty"`
}

PipelineStage describes one template and its artifact contract.