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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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