Skip to content

Documentation: Update assessment contract #1157

Description

@vprashrex

Is your feature request related to a problem?
The assessment architecture docs under docs/architecture/assessment/ describe an outdated batch contract. This leads to confusion and misinformation for readers due to the changes made in the config/input reshape.

Describe the solution you'd like
Update the following documentation to reflect the new contract:

  • docs/architecture/assessment/README.md
  • docs/architecture/assessment/api-contract.md
  • docs/architecture/assessment/configuration-and-versioning.md
  • docs/architecture/kaapi-ai-assessment-ARCHITECTURE.md

Key contract changes to include:

  1. Remove query from request input; BATCH input format is now { "data": [...] }. RESPONSE input contains only attachments.
  2. Move prompt template to config as submission, mandatory on assessment.params.submission.
  3. Elevate input_schema to the config_blob level, making it mandatory and non-empty.
  4. Eliminate the duplicate_detection pre-filter completely.
  5. Implement placeholder validation at config-save, requiring {column} in submission to resolve against input_schema.
Original issue

Problem

The assessment architecture docs under docs/architecture/assessment/ still describe the OLD BATCH contract (request query template, input_schema nested under assessment.params, a duplicate_detection pre-filter). After the config/input reshape (#1154, #1153) these are stale and mislead readers.

Scope

Update the following to the new contract — prose, JSON examples, and tables. Do not touch the .png assets.

  • docs/architecture/assessment/README.md
  • docs/architecture/assessment/api-contract.md
  • docs/architecture/assessment/configuration-and-versioning.md
  • docs/architecture/kaapi-ai-assessment-ARCHITECTURE.md

Contract changes to reflect

  1. query removed from the request input. BATCH input = { "data": [...] } (detected by the data key). RESPONSE input carries only attachments and still returns 501.
  2. Prompt template moves into the config as submission — mandatory on assessment.params.submission, optional per pre-filter's params.submission. Interpolated server-side per row.
  3. input_schema hoisted to the config_blob top level (sibling of pre_filters/assessment), mandatory and non-empty — no longer under assessment.params.
  4. duplicate_detection pre-filter removed entirely (incl. knowledge_base_id and the output.pre_filter.duplicate_detection result field). Only topic_relevance remains.
  5. Placeholder validation now at config-save (every {column} in a submission must resolve against the top-level input_schema); runtime validates only the structured data rows.

Acceptance criteria

  • No doc describes a request query field or a duplicate_detection pre-filter.
  • All JSON examples show top-level input_schema, submission in the config, and data-only request input.
  • Config-save vs runtime validation split documented.
  • .png assets untouched.

Related: #1153, #1154.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
In Review

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions