ProjectTech4DevAI / ProjectTech4DevAI/kaapi-backend

Documentation: Update assessment contract

Open
#1,157 0 comments 0 reactions 1 assignee View on GitHub

@vprashrex is already working on this.

Since Aug 25, 2026.

  • #1017 by @vprashrex — open
documentation
Dominant language
Python
Stars
18
Forks
10
Avg merge
2d 20h
Merged PRs (30d)
14

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.