Markdown -> JSONL LLM Classification Method

Date: June 25, 2026

Purpose

Record the method by which the make_md web converter determines which JSONL target—docs_chunks, api_mapping, or label_prototypes—to send official documentation Markdown to the LLM.

This document does not store web app code or API keys. Based on the currently running local implementation, it outlines what input is given to the LLM and what output is allowed.

Current Execution Status

The local web UI runs at the following address.

http://localhost:8501/

The current execution process is running from /Users/joyeongjin/make_md with streamlit run app.py --server.port 8501.

Classification Call Location

In the current implementation, table classification is handled by classify_tables().

/Users/joyeongjin/make_md/app.py

Classification calls are executed before transformation.

-> classify_tables()
-> Selected table list
-> call_qwen_api() per table
-> Create JSONL record
-> validate_record()
-> Save

LLM Input

The inputs passed to the LLM at the classification stage are the following three.

Input	Description
system message	Forces the response to be JSON only. Markdown, explanations, and thinking text are prohibited.
filename	Name of the uploaded Markdown file
full markdown	Entire Markdown body

The classification stage must send the entire Markdown document. Sending only an excerpt of the beginning is not allowed. If classification is based only on the front part of the official documentation, documents whose boundaries become apparent in later examples or detailed explanations—such as api_mapping and label_prototypes—may be misclassified.

LLM Output Format

The LLM must return exactly one JSON array.

Allowed values:

["docs_chunks", "api_mapping", "label_prototypes"]

Example:

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[] is used only when it is determined that the content is not useful official documentation.

Current Prompt Summary

The core of the classification prompt should be as follows.

Classify this Markdown into zero or more target tables.
Return exactly one JSON array.
Valid values are:
["docs_chunks", "api_mapping", "label_prototypes"]

Table boundaries:
- docs_chunks: official documentation explanations, tutorials, class reference chunks.
- api_mapping: Godot 3 -> Godot 4 function/class/symbol name changes.
- label_prototypes: usage-pattern migrations where arguments, call shape, or usage style changed, not just the name.

Rules:
- Use [] only if the file is not useful documentation content.
- Use one or more valid table names when conversion is needed.
- Do not include explanations, markdown fences, or any text outside JSON.

FILE: <filename>
FULL MARKDOWN:
<entire markdown text>

Criteria for Determination

The LLM must be provided with the boundaries of three tables together.

Table	Intended Boundary
`docs_chunks`	Official documentation description body, tutorials, class reference chunks
`api_mapping`	How function names, class names, and symbol names changed from Godot 3 → Godot 4
`label_prototypes`	How to write when the usage pattern, argument composition, or call pattern of a function changes entirely

The boundaries of api_mapping and label_prototypes are especially important. If only the name changed, it belongs to api_mapping; if the argument composition or call method itself changed, it belongs to label_prototypes.

JSON Correction Flow

If the LLM does not return a proper JSON array, send a correction request once more.

The core of the correction request is as follows.

Your previous classification response was not valid JSON.
Rewrite it as exactly one JSON array using only these strings:
["docs_chunks", "api_mapping", "label_prototypes"].
Use [] only if this file is not useful documentation content.

If the correction request also fails, the file is recorded as a classification error.

Whether to use hardcoding fallback

The current classification stage does not force table selection, using a hardcoding fallback based on file name, path, and regular expressions.

If there is no API key, classification is not performed. If the Qwen response is not a valid JSON array and correction also fails, it does not arbitrarily select a table to save, but leaves it as an error.

Debug log

The classification results are recorded in the session state in the following format.

{
  "file": "example.md",
  "parsed_result": ["docs_chunks"],
  "matched_tables": ["docs_chunks"],
  "raw_response": "<qwen raw response>"
}

This record is used to identify the cause when Qwen responded with something other than JSON, returned [], or gave an invalid table name.