ProjectTech4DevAI / ProjectTech4DevAI/kaapi-backend
Documentation: Update assessment contract
- 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.mddocs/architecture/assessment/api-contract.mddocs/architecture/assessment/configuration-and-versioning.mddocs/architecture/kaapi-ai-assessment-ARCHITECTURE.md
Key contract changes to include:
- Remove
queryfrom request input; BATCH input format is now{ "data": [...] }. RESPONSE input contains onlyattachments. - Move prompt template to config as
submission, mandatory onassessment.params.submission. - Elevate
input_schemato theconfig_bloblevel, making it mandatory and non-empty. - Eliminate the
duplicate_detectionpre-filter completely. - Implement placeholder validation at config-save, requiring
{column}insubmissionto resolve againstinput_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.mddocs/architecture/assessment/api-contract.mddocs/architecture/assessment/configuration-and-versioning.mddocs/architecture/kaapi-ai-assessment-ARCHITECTURE.md
Contract changes to reflect
queryremoved from the requestinput. BATCHinput={ "data": [...] }(detected by thedatakey). RESPONSE input carries onlyattachmentsand still returns 501.- Prompt template moves into the config as
submission— mandatory onassessment.params.submission, optional per pre-filter'sparams.submission. Interpolated server-side per row. input_schemahoisted to theconfig_blobtop level (sibling ofpre_filters/assessment), mandatory and non-empty — no longer underassessment.params.duplicate_detectionpre-filter removed entirely (incl.knowledge_base_idand theoutput.pre_filter.duplicate_detectionresult field). Onlytopic_relevanceremains.- Placeholder validation now at config-save (every
{column}in asubmissionmust resolve against the top-levelinput_schema); runtime validates only the structureddatarows.
Acceptance criteria
- No doc describes a request
queryfield or aduplicate_detectionpre-filter. - All JSON examples show top-level
input_schema,submissionin the config, anddata-only request input. - Config-save vs runtime validation split documented.
-
.pngassets untouched.
Related: #1153, #1154.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.