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, concrete-request validation, explicit smoke diagnostics, 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, smoke diagnostics, 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 of final backend definitions, including diagnostic metadata, plus capacity policies validated by the configuration adapter.	Backend registry
internal/configuration	Loads keyed backend, profile, and prompt configuration through ConfigKit; records effective field presence, validates final values including optional diagnostic metadata, captures indexed prompt definitions, referenced message content, compiled templates, input metadata snapshots, sorted identity-only backend, 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, validation, and source-neutral smoke diagnostics, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, output contracts, and resource-identity syntax and qualification. 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 caller-selected configuration into one snapshot, then constructs shared capacity, rendering, validation, generation, repair, the ordinary runner, and the smoke tester for each engine. Immutable namespace views share those collaborators and qualify caller-supplied execution, inspection, and diagnostic selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. 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, ordinary attempt observations, and invocation-local evidence for diagnostics.	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 response decoding, authentication, deadline handling, per-invocation HTTP evidence and built-in diagnostic probes, 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; smoke diagnostics keep their private evidence outside ordinary observer events.	Internal execution observation
internal/usecase	Selects captured prompts and profiles, enumerates requirements from captured prompt syntax, applies request overrides and completion checks, coordinates ordinary and single-claim prepared execution across rendering, artifact loading, operation-local validation plans, generation, capacity, and bounded repair, and runs explicit smoke diagnostics with private cases, shared generation/capacity, and optional built-in HTTP probes.	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.