Record the PromptKit-native architectural direction

This commit is contained in:
2026-11-18 18:58:21 +00:00
parent af250eb72f
commit 69c4054eea

View File

@@ -5,17 +5,19 @@
Working notepad for reviewing the ownership boundaries in the
[PromptKit v0.23.2 adoption roadmap](promptkit.md). Work through the topics
below in order, recording questions, evidence, decisions, and follow-up work.
The six initial topics are proposals for discussion, not accepted changes.
Item 1 records the selected architectural direction; its detailed design and
the remaining topics are still under discussion.
The Audita comparison is a seventh topic and may inform earlier decisions.
The central question is how much reusable LLM machinery Notarius should retain
as PromptKit, ConfigKit, and CommandKit take on more responsibility. A working
principle to evaluate is that application ownership of a policy does not
necessarily require application ownership of its implementation.
The goal is to make Notarius fully PromptKit-native and adopt modern PromptKit
capabilities as fully as practical. Application ownership of a policy does not
necessarily require application ownership of its implementation. Evaluate
remaining machinery against this goal, including opportunities for upstream
features where PromptKit does not yet meet an application need.
No architectural changes have been agreed or implemented through this notepad.
The adoption roadmap remains the migration plan; reconcile it with decisions
from this discussion as they are made. Significant changes to accepted
No application changes have been implemented through this notepad. The adoption
roadmap still needs reconciliation with the selected direction; its adapter
preservation language is subject to this review. Significant changes to accepted
architecture need successor ADRs under the
[documentation policy](../policy/documentation.md#architecture-decision-records).
Current boundaries are described in [Architecture](../policy/architecture.md)
@@ -23,23 +25,54 @@ and [LLM Runtime Internals](../internal/llm.md).
## 1. LLM API And Diagnostic Boundary
Consider using native PromptKit contracts in LLM-facing implementation packages
and reducing parallel completion, message, usage, execution-summary, and debug
types. Retain application contracts where they serve typed artifact handling,
stage context, durable output compatibility, or disclosure policy.
**Discussion / decision:** Direction selected: remove the Notarius PromptKit
adapter and make the application fully PromptKit-native. Detailed design and
migration consequences remain to be worked through.
Questions:
### Background And Intent
- Which abstractions express Notarius behavior, and which merely copy PromptKit?
- Where should direct PromptKit dependencies be permitted?
- Can detailed debug material flow to an application-controlled writer without
being translated through generic pipeline contracts?
- Which persisted representations need compatibility or redaction adapters?
Notarius and related applications, including Audita, originally developed their
own LLM interfaces or used the OpenAI SDK directly. PromptKit emerged by
extracting their duplicated mechanics into a shared library. Notarius adopted
an early version and predates many of the library's modern capabilities.
**Discussion / decision:** Pending. Start here.
The maintainer clarified that duplication of PromptKit capabilities, including
slight behavioral differences, does not reflect an intentional requirement for
an independent Notarius implementation. Existing wrappers, tests, and historical
decisions are migration evidence, not sufficient reasons to preserve that
duplication. Identify actual application needs before choosing what to retain.
**Follow-up:** Identify the smallest useful application boundary and any
architecture-policy changes it requires.
Missing reusable capabilities may justify upstream feature requests. The
discussion is not constrained to what v0.23.2 can replace immediately; any
resulting change to the adoption target remains to be selected.
### Design Consequences To Work Through
- Use native PromptKit APIs and contracts for LLM execution instead of preserving
a parallel provider-neutral completion API or rebuilding the adapter under
another name.
- Review copied request, result, error, inspection, observation, and debug types
for removal. Keep application-owned representations only where they serve a
concrete application need, with compatibility decisions made explicitly.
- Let PromptKit provide reusable execution mechanics. Determine how Notarius
supplies domain inputs, interprets typed outputs, and expresses its acceptance
decisions through the resulting design.
- Review application composition, test seams, diagnostic storage, and disclosure
handling without assuming they require an LLM abstraction layer.
- Evaluate each upstream gap as a requirement to understand and potentially
address in PromptKit, rather than automatically preserving local machinery.
Open questions:
- What application collaborators and helpers remain after the adapter is removed?
- Which durable output or diagnostic contracts need deliberate migration?
- Which existing behavioral differences should disappear through native adoption,
and which reflect an application need that should be supplied to PromptKit?
**Follow-up:** Apply this direction to items 2–6, compare Audita under item 7,
and reconcile the adoption roadmap. Record the significant boundary change in
a successor ADR and update architecture and implementation documentation when
the change lands. Do not treat the remaining topics as decided by this direction.
## 2. Prompt Assets And Schema Assembly