Architectural improvements in the http adapter
This commit is contained in:
@@ -1,14 +1,14 @@
|
||||
# Analyzer Architecture
|
||||
# Scriptorium Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
Analyzer is a general-purpose prompt-profile execution service.
|
||||
Scriptorium is a general-purpose prompt-profile execution service.
|
||||
|
||||
Its job is to take one or more named input artifacts, render a configured prompt profile, execute that prompt against an LLM endpoint, optionally validate the output, and return a generated artifact with useful metadata.
|
||||
|
||||
The initial concrete use case is generating artifacts from cleaned Dungeons & Dragons session transcripts, such as session recaps, player analysis, structured event extraction, and glossary update suggestions.
|
||||
|
||||
However, Analyzer must not be D&D-specific. D&D behavior belongs in prompt profiles, schemas, and caller-provided inputs. The Go application should remain a generic engine for prompt execution and output validation.
|
||||
However, Scriptorium must not be D&D-specific. D&D behavior belongs in prompt profiles, schemas, and caller-provided inputs. The Go application should remain a generic engine for prompt execution and output validation.
|
||||
|
||||
## Intended Audience
|
||||
|
||||
@@ -28,7 +28,7 @@ The desired implementation style is:
|
||||
|
||||
## Core Concept
|
||||
|
||||
Analyzer transforms:
|
||||
Scriptorium transforms:
|
||||
|
||||
- Prompt profile
|
||||
- Named input artifacts
|
||||
@@ -44,19 +44,19 @@ Into:
|
||||
- Raw model output
|
||||
- Structured error details, if applicable
|
||||
|
||||
Analyzer should be thought of as a deterministic wrapper around a nondeterministic model call.
|
||||
Scriptorium should be thought of as a deterministic wrapper around a nondeterministic model call.
|
||||
|
||||
The system should make the model call as auditable and reproducible as possible, even though LLM output itself may not be exactly reproducible.
|
||||
|
||||
## Application Boundary
|
||||
|
||||
Analyzer is not an orchestrator.
|
||||
Scriptorium is not an orchestrator.
|
||||
|
||||
The broader workflow may include audio transcription, transcript merging, transcript polishing, artifact persistence, and notifications. Those responsibilities belong to the external orchestrator, currently expected to be Narratio.
|
||||
|
||||
Analyzer should not know about WhisperX, Seriatim, Audita, or any other pipeline stage.
|
||||
Scriptorium should not know about WhisperX, Seriatim, Audita, or any other pipeline stage.
|
||||
|
||||
Analyzer only knows how to:
|
||||
Scriptorium only knows how to:
|
||||
|
||||
1. Load a prompt profile.
|
||||
2. Load or receive named input artifacts.
|
||||
@@ -75,19 +75,19 @@ The initial D&D workflow is expected to look like this:
|
||||
4. Narratio saves the merged transcript.
|
||||
5. Narratio calls Audita to polish the transcript.
|
||||
6. Narratio saves the processed transcript.
|
||||
7. Narratio calls Analyzer one or more times to generate output artifacts.
|
||||
7. Narratio calls Scriptorium one or more times to generate output artifacts.
|
||||
8. Narratio saves each generated artifact.
|
||||
9. Narratio optionally sends a completion notification.
|
||||
|
||||
Analyzer only owns step 7.
|
||||
Scriptorium only owns step 7.
|
||||
|
||||
Each Analyzer request should initially produce one artifact. If multiple artifacts are needed, the orchestrator should call Analyzer multiple times.
|
||||
Each Scriptorium request should initially produce one artifact. If multiple artifacts are needed, the orchestrator should call Scriptorium multiple times.
|
||||
|
||||
Batch execution can be added later, but should not be part of the core v1 design unless there is an immediate need.
|
||||
|
||||
## Primary Use Cases
|
||||
|
||||
Analyzer should support the following v1 use cases:
|
||||
Scriptorium should support the following v1 use cases:
|
||||
|
||||
1. Generate a freeform Markdown artifact from a transcript and prompt profile.
|
||||
2. Generate a structured JSON artifact from a transcript and prompt profile.
|
||||
@@ -129,7 +129,7 @@ The central use case should be easy to test with fake prompt repositories, fake
|
||||
|
||||
Recommended high-level structure:
|
||||
|
||||
- cmd/analyzer: application entrypoint
|
||||
- cmd/scriptorium: application entrypoint
|
||||
- internal/domain: core domain types
|
||||
- internal/usecase: application use cases
|
||||
- internal/profile: prompt profile loading and parsing
|
||||
@@ -425,7 +425,7 @@ If token counting is not implemented initially, use byte-size limits or leave to
|
||||
|
||||
## Output Formats
|
||||
|
||||
Analyzer should support at least these output formats:
|
||||
Scriptorium should support at least these output formats:
|
||||
|
||||
- markdown
|
||||
- text
|
||||
@@ -454,7 +454,7 @@ Validation modes:
|
||||
- json: parse as JSON
|
||||
- json_schema: parse as JSON and validate against schema
|
||||
|
||||
For invalid structured output, Analyzer should return:
|
||||
For invalid structured output, Scriptorium should return:
|
||||
|
||||
- Validation status
|
||||
- Validation errors
|
||||
@@ -540,9 +540,9 @@ It should support local development and pipeline usage.
|
||||
|
||||
Suggested commands:
|
||||
|
||||
- analyzer run
|
||||
- analyzer profiles list
|
||||
- analyzer profiles inspect
|
||||
- scriptorium run
|
||||
- scriptorium profiles list
|
||||
- scriptorium profiles inspect
|
||||
|
||||
The run command should accept:
|
||||
|
||||
@@ -575,7 +575,7 @@ Avoid hardcoding D&D-specific defaults.
|
||||
|
||||
## Artifact Storage
|
||||
|
||||
Analyzer does not need to own artifact persistence in v1.
|
||||
Scriptorium does not need to own artifact persistence in v1.
|
||||
|
||||
The default behavior should be:
|
||||
|
||||
@@ -584,7 +584,7 @@ The default behavior should be:
|
||||
|
||||
Narratio or another orchestrator can save the result to S3.
|
||||
|
||||
However, Analyzer should be designed so that artifact readers and writers can be added later.
|
||||
However, Scriptorium should be designed so that artifact readers and writers can be added later.
|
||||
|
||||
If an ArtifactWriter is added, it should be optional and should not change the core use case.
|
||||
|
||||
@@ -606,7 +606,7 @@ Important error categories:
|
||||
|
||||
Validation failure is not necessarily the same as application failure.
|
||||
|
||||
If the model returns output but the output fails validation, Analyzer should return a structured RunResult with failed validation status when possible.
|
||||
If the model returns output but the output fails validation, Scriptorium should return a structured RunResult with failed validation status when possible.
|
||||
|
||||
Transport-level errors, missing inputs, invalid profiles, and failed model calls should be returned as application errors.
|
||||
|
||||
@@ -656,7 +656,7 @@ This metadata is important for auditing and regeneration.
|
||||
|
||||
## Security and Safety Considerations
|
||||
|
||||
Analyzer will often handle private transcripts or documents.
|
||||
Scriptorium will often handle private transcripts or documents.
|
||||
|
||||
Default behavior should avoid accidental disclosure.
|
||||
|
||||
@@ -740,11 +740,11 @@ Do not discard invalid model output.
|
||||
|
||||
Do not hide validation errors.
|
||||
|
||||
Do not implement an orchestrator inside Analyzer.
|
||||
Do not implement an orchestrator inside Scriptorium.
|
||||
|
||||
## Summary
|
||||
|
||||
Analyzer is a reusable prompt-profile execution engine.
|
||||
Scriptorium is a reusable prompt-profile execution engine.
|
||||
|
||||
It should provide this core transformation:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user