promptkit/docs/internal/overview.md

Internal Component Overview

Purpose

This document inventories Promptkit's implemented components for contributors. The architecture policy owns durable boundary and dependency rules. See the development guide for contributor workflow and validation.

Implemented Components

Component	Implemented responsibility	References
Root promptkit package	Provides the supported engine facade, ConfigKit source helpers, profile and backend mapping conveniences, injection options, public requests and results, prompt/profile/requirement inspection and identity listing, observation values, opaque prepared-execution handles, value conversion, redacted formatting, and typed capacity and generation error mapping.	Package GoDoc, observations, prepared execution, backend API, engine facade, identity listing, requirement facade
examples/go-library/prepare	Demonstrates offline preparation and explicit configuration inspection with a prompt file, programmatic profile, and inline input. It is not a public library package.	Example program
examples/go-library/run	Demonstrates an offline downstream consumer using a prompt file, programmatic profile, inline input, an injected deterministic model client, and Run. It is not a public library package.	Example program
examples/go-library/observe	Demonstrates offline built-in HTTP retry and synchronous metadata observation across structured proposal and assessment runs using embedded sources, two profiles on one finite backend, and an application decision. It is not a public library package.	Example program
internal/backend	Holds a defensive, immutable lookup and capacity-policy index for final backend definitions validated by the configuration adapter.	Backend registry
internal/catalog	Selects released keyed catalog assets and PromptKit-owned profile definitions as ConfigKit underlays; effective validation belongs to the configuration loader.	Catalog adapter, internal sources
internal/configuration	Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values, captures indexed prompt definitions, referenced message content, compiled templates, input metadata snapshots, sorted identity-only profile and prompt inventories, backend and presence-aware profile snapshots, and an explicit read-only inspection view.	Typed loader, identity listing, internal sources
internal/capacity	Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping.	Internal capacity management
internal/domain	Defines internal framework values for requests, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers.	Domain declarations, requirement values, endpoint invariant
internal/engine	Assembles selected catalog and caller configuration into one snapshot, then constructs capacity, rendering, validation, generation, repair, and the use-case runner for each engine. It delegates identity listing directly to the captured configuration inventory rather than the runner.	Engine assembly, internal sources, internal runner
internal/generation	Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, and attempt observations.	Internal generation coordination
internal/defaults	Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits.	Framework defaults
internal/filecatalog	Provides deterministic YAML discovery and path helpers for operating-system filesystems and fs.FS sources.	File catalog
internal/jsonvalue	Validates and deeply copies bounded JSON-compatible extra-parameter and prepared-schema trees while preserving supported concrete value types and rejecting cycles or excessive depth and work.	JSON values
internal/promptdef	Provides a narrow captured-prompt lookup contract, not-found identity, and execution-ready definition hash.	Prompt lookup, framework formats
internal/profile	Provides a narrow captured-profile lookup contract and not-found identity.	Profile lookup, framework formats
internal/prompt	Renders prompt messages from Go templates with artifact, variable, session, and cache-control data, and conservatively enumerates dependencies from captured template syntax.	Go-template renderer, requirement discovery
internal/artifact	Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes.	Internal sources and validation
internal/validate	Validates basic, JSON, and JSON Schema output using operating-system filesystem or fs.FS schema sources and creates operation-local validation plans with canonical contained schema resources.	Framework formats, internal sources and validation
internal/llm	Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including bounded structured non-success response decoding, successful-response decoding, authentication, deadline handling, and ownership of the OpenAI-compatible reserved request-field policy.	Internal model client
internal/observation	Owns invocation-local run IDs, presence-aware usage and phase accounting, and synchronous metadata event delivery for ordinary and claimed prepared runs and generation attempts.	Internal execution observation
internal/usecase	Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, and coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair.	Internal runner, requirement inspection, prepared-execution implementation

The internal engine assembles these internal components without exposing their representations. Consumers depend only on the root facade.

Maintenance

Update this inventory as implementation adds packages or changes component responsibilities. List only implemented components; proposed package boundaries belong in temporary planning documents until their implementation lands.