From 69c4054eea199e5ecee453ef40edc529c6c671f9 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 18 Nov 2026 18:58:21 +0000 Subject: [PATCH] Record the PromptKit-native architectural direction --- .../promptkit-architecture-discussion.md | 75 +++++++++++++------ 1 file changed, 54 insertions(+), 21 deletions(-) diff --git a/docs/roadmap/promptkit-architecture-discussion.md b/docs/roadmap/promptkit-architecture-discussion.md index 0b977f19..d14d8cf5 100644 --- a/docs/roadmap/promptkit-architecture-discussion.md +++ b/docs/roadmap/promptkit-architecture-discussion.md @@ -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