Record the PromptKit-native architectural direction
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user