sarry12227/pathway-atlas

PathwayAtlas

Turn a single consultation into a resumable, anonymous planning session. The host is responsible for real-time search, browsing, and extraction of public materials. By default, scripts/host_workflow.py acts as a facade, calling scripts/planning_session.py to save unique state and replay typed receipts across processes. Deterministic modules only consume the confirmed profile, canonical QueryPlan, and fresh evidence bundle. The user only answers natural language questions and confirms their profile — they never touch internal JSON, file paths, or commands.

Profile Confirmation

The first reply can only auto-fill answers already identified in the user's initial message and display the complete questionnaire below. Ask the user to verify, complete, or modify everything in one go. Do not re-ask for information already provided. Each question must have a clear answer; "Don't know," "Not sure," or "Prefer not to say" are acceptable. Do not delete a question because the answer is unknown.

1. Gender Options: Male / Female / Prefer not to say.
2. Province of Gaokao registration Fill in the province where you registered for the Gaokao; do not fill in a detailed address.
3. Current city and high school Fill in your current city and the full name of your high school; do not fill in a class number.
4. Grade and expected Gaokao year Options: Freshman / Sophomore / Senior; also confirm the expected Gaokao year.
5. Class type / tracking Fill in the class type/tracking, e.g., regular class, key class, competition class; do not fill in specific class numbers.
6. Subject combination Fill in the format "Physics + Chemistry + Biology," etc., and indicate whether scores are raw scores or scaled scores.
7. Total score of most recent major exam Fill in the exam name, date, scope, full marks, and your total score.
8. School ranking (grade ranking) of most recent major exam Fill in the rank, ranking basis, and number of reference students in the same basis. If there are provincial or large-scale joint exam percentile ranks, include them together.
9. Highest and typical school rank in the past Fill in the highest historical rank and corresponding exam, and the typical rank range during normal performance. If unknown, explicitly state "unknown."
10. Awards and achievements Fill in subject competitions, innovation competitions, English competitions, essay competitions, etc. If none, write "None."
11. Special activity experience Fill in research trips, summer camps, social practice, volunteer work, etc. If none, write "None."
12. Ideal universities List one to five ideal universities. If no clear goal, write "Uncertain."
13. Why do you want to attend these schools? Multiple choice: High reputation / High ranking; Strong programs in specific fields; Good city / Excellent location; Family connections / Recommendations; Test scores fit well; Heard from teachers / classmates; Other.
14. What major(s) do you want to study? Multiple choice: Computer Science / Software / AI; Electronics / Communication Engineering; Electrical Engineering / Automation; Mechanical Engineering / Aerospace; Energy & Power / Materials Science; Civil Engineering / Architecture; Mathematics / Physics / Chemistry / Biology (Basic Sciences); Clinical Medicine / Stomatology; Pharmacy / Nursing; Law; Accounting / Finance / Economics; Chinese Language & Literature / Journalism & Communication / History / Philosophy; Foreign Languages (English / less-commonly taught languages); Management (Business Administration / HR, etc.); Education / Psychology; Other.
15. Why do you want to study this major? Multiple choice: Personal interest / Passion for the field; Good employment / High salary; Family advice / Family business in the field; Heard it's a promising / high-growth field; Teacher recommendation; Peers are choosing it; Other.
16. Which city or region do you want to attend university in? Multiple choice: Beijing / Shanghai / Guangzhou / Shenzhen / Wuhan / Hangzhou / Nanjing / Suzhou / Chengdu / Chongqing / Xi'an; Other first-tier cities; Other provincial capitals; Doesn't matter, as long as the school is good; Also fill in regions you cannot accept.
17. What do you envision doing after university? Multiple choice: Work directly to gain professional experience; Pursue graduate studies (master's/PhD); Take civil service / public institution exams for stability; Study abroad to broaden horizons; Start my own business; Haven't decided yet, take it step by step; Other.
18. What are you most anxious or worried about? Multiple choice: Child's grades are unstable, worried about underperforming in Gaokao; Don't know what major the child is suited for, worried about choosing the wrong path; Worried that even if scores are enough, a wrong school/major will be chosen; Don't know about other pathways besides Gaokao; Child has no award experience, worried about impacting the Strong Base Plan / Comprehensive Evaluation; Child lacks motivation and needs external encouragement and guidance; Completely unfamiliar with the rules of preference filling, afraid of making mistakes; Family has special circumstances (financial, health, hukou, etc.), don't know what policies can be used; Other.
19. What problem do you most want the planning plan to solve? Fill in one to three sentences describing the specific help you expect.
20. Planning conditions, restrictions, and special pathways Answer with a multiple-choice matrix: National Special / Local Special / University Special eligibility; Strong Base Plan / Comprehensive Evaluation; Government-funded Teacher / Excellent Teacher Plan / Directed Rural Medical Student; Military / Police / Judicial / Firefighting / Maritime; Hong Kong/Macau universities / Sino-foreign cooperation / Overseas study; Arts / Sports / Competition or subject specialties; Hukou / School registration / Urban/rural attributes; Foreign language type and approximate level; Medical check / Vision / Color vision / Political review / Physical fitness restrictions; Willingness to accept service period / Directed employment / Geographic constraints; Tuition and living expense affordability; Accept private / Sino-foreign cooperation / High-tuition programs; School priority / Major priority / Balanced; Accept major adjustment or not; Risk preference for Reach-Match-Safe strategy. Each item can be answered with "Yes," "No," "Uncertain," or "N/A"; do not ask for a detailed address or medical history.

Refuse to collect student names, phone numbers, addresses, specific class numbers, communication IDs, credentials, or local paths. The full high school name can be used for public anchor retrieval, but the report remains anonymous. Inside the host, the Agent first uses scripts.questionnaire_intake.parse_numbered_questionnaire(...) to segment the user's natural language responses, then performs host normalization only according to the user's explicit meaning, and passes the result to build_profile_from_questionnaire(...) to form a v3 PlanningProfile. For question 8, when both school ranking and joint exam percentile rank are provided, the school ranking is kept as the primary observation, and each city-level or provincial-level joint exam percentile rank is separately normalized into additional_observations with scope explicitly set to city_joint or province_joint, source set to joint_exam_report; they must not be collapsed into a single rank. Readiness, advantages, or research experience that the user does not explicitly answer must remain unknown or empty; do not fabricate these based on subject choices, activities, or a lack of restrictions. Do not ask the user to create JSON, provide local paths, or select files. After loading the trusted province directory, obtain the mode from ProvinceConfig.mode, and use canonical subject keys for subject combinations; do not hardcode province modes.

Do not run preflight, query plans, or retrieval before profile confirmation, and do not calculate, recommend, or judge. After the user replies, summarize the known values, unknown values, and hard constraints point by point, and ask the user to explicitly confirm. The confirmed anonymous profile is the only complete context for all subsequent reasoning, retrieval, calculation, and output. When the user modifies the profile, create a new version and invalidate the affected downstream states.

When there is no official percentile rank, use the school, class type, exam scope, scores, school or joint exam rank, reference student count, highest and typical performance, and public historical anchors to generate optimistic, neutral, and conservative percentile rank ranges, and then generate estimated rank reference versions for the reach-match-safe school pools. Only when there is absolutely no calibration basis should numbers not be generated, but the multi-path assessment should still be completed, and at least the missing calibration materials should be listed.

Completion criteria: All 20 questions have explicit answers or explicit "unknown" status, and the user has confirmed the anonymous profile.

Session Initialization

Only after profile confirmation, following references/host-workflow.md, the host runs in its private workspace: python -m scripts.host_workflow start --workspace … --answers … --confirmed. The start command internally completes the original state machine's init, confirm, capability pre-check, canonical QueryPlan binding, and journal checkpoint. The user does not create directories or enter commands. Select the capability mapping: generic, Codex, Claude Code, or Kimi.

Only pass the currently real callable capabilities — search, browse, vision — as repeated --host-capability parameters to start. local_exec and file_output are separately recorded workflow gates. Preflight machine grades are only full, standard, offline. Capability loss can only reduce coverage, not change evidence rules. Then use python -m scripts.host_workflow next --workspace … --session … to read the next batch of tasks. The status is returned by this command's JSON. Exit code 2 means the input, extraction, or evidence is invalid and the last checkpoint was preserved; exit code 3 means an optional capability is unavailable.

Completion criteria: The session is in query_plan_ready, returns session ID and typed next tasks, saves all degradations, and does not expose absolute paths or raw exceptions to the user.

Research Loop

Using the typed QueryTask returned by next, search, open, and save public materials item by item according to the retrieval playbook. After the host writes a submission as defined in references/host-workflow.md, run: python -m scripts.host_workflow ingest --workspace … --session … --task … --submission …, which calls ingest. If it cannot be completed, run the same facade's unavailable with a real reason. After each, repeatedly call next in a loop until there are no pending tasks. The facade possesses the journal, evidence bundle, completed outcomes, and recovery context. The Agent only prepares public materials and their extraction configurations; it does not manually piece together receipt, digest, or journal JSON.

Each task maintains ProvinceConfig.mode, normalized subject_group, required_extraction_fields, availability, freshness, and bounded max_candidates. Do not set a fixed Top-N. Search only discovers candidates; you must open the original webpage or attachment — do not treat search snippets as facts. Extract using the task-specified adapter (HTML, XLSX, PDF, OCR, or QR). Download only through the secure downloader, and save year, method, locator, source provenance, coverage, and warnings.

Query all annual data in order: Y → Y-1 → Y-2 → Y-3. If the latest year is missing, unavailable, or unpublished, search backward year by year, up to three years. Each data type independently selects the most recent comparable year; do not stop the entire plan because one item is missing. Cover at least: score-percentile tables, admission percentile ranks, admission plans, admission regulations, tuition fees, subject requirements, multi‑path policies, service periods, and breach-of-contract clauses. When only third‑party materials exist for the current year while official materials exist for the previous year, retain both: mark the former as a current‑year reference and the latter as a historical baseline. If the system or scope changes make them incomparable, stop numerical aggregation and explain why.

Regular batch admissions only go through scripts.adapters.admission_bridge, which combines exact adapter rows, the corresponding QueryTask, ValidatedAdmissionRow, and extraction coverage. The entire row binding is delegated to admission_row_hash, with coverage_status separate from evidence status. Use typed rank/pathway bridges respectively; use quote/span‑bound public_text adapter for public prose; omitted fields remain missing. Do not manually piece together facts or fabricate province.json.

The facade's ingest performs bridge → receipt → ingest within the same host process: it uses the typed bridge produced by the exact adapter to call scripts.planning_session.build_task_evidence_outcome(profile, query_plan, task, bridges), then completes the task with session.ingest_task(..., evidence_outcome=task_evidence_outcome) and internal checkpointing. The evidence_outcome=, factory‑only receipt, complete origin replay, and bare digest (without authorization capability) are invariants; the Agent does not invoke these underlying steps.

Offline mode only consumes authenticated locally provided materials and does not claim current or real‑time verification; there is no silent fallback to network. Each task must ultimately be ingested as completed or ended with a controlled unavailable reason.

Completion criteria: next no longer returns query tasks; each task has exactly one replayable outcome.

Evidence Finalization

Following the source policy, perform publisher grading, independence checks, deduplication, adoption, and conflict resolution. Conflicts must not be averaged or resolved by picking a convenient value. Grade A original sources can form official. If no Grade A is available, two independent Grade B sources that agree can form corroborated. Three independent Grade C sources that agree can form reference. When official sources are missing, unavailable, or not found, continue searching for Grade B/C. A single third‑party source that does not reach the threshold can only be used as a discovery clue or the basis for an "observation."

After all tasks are completed or unavailable, run: python -m scripts.host_workflow finish --workspace … --session … --format markdown. The facade first performs validation semantic equivalents of python scripts/validate_data.py / python scripts/validate_evidence.py, then internally calls scripts.planning_session.build_evidence_manifest_outcome(...) and session.finalize_evidence(evidence_outcome, ...) to cross the finalize gate and save a checkpoint. Do not give numbers or start calculations before forming an authenticated snapshot. When the adoption threshold is not met, retain partial, conflict, or missing; do not lower the threshold. The bare digest of the manifest has no effect.

Pathways flagged as include or discover in the confirmed profile or canonical QueryPlan must not disappear from the report due to a policy being missing, masked, partial, or conflict. Retain them through typed pathway observations marked as "observation + pending verification": only carry the real existing source number and original evidence status, clearly indicating the gap and the policy/qualification verification action. When there is no source, the source number remains empty. Do not fabricate policy content, institutions, qualification conclusions, target percentile ranks, policy years, application timelines, or source numbers for observation items. When a replayable accepted policy already exists for the same plan target, replace the observation with the original formal recommendation logic.

Completion criteria: The fresh evidence bundle and research snapshot are authenticated. Output that depends on missing facts has a clear unavailable reason.

Calculation & Publication

finish internally executes the compute gate: it only passes outcomes bound by finalize_evidence to scripts.planning_session.build_calculation_outcome(...), then calls session.with_calculation(...) to save a checkpoint, and atomically publishes using scripts.planning_session.build_report_publication_outcome(...) and session.publish_report(...). Calculations only consume validated snapshots, dataset/config, normalized rows, the complete profile, canonical QueryPlan, and versioned decision policies. They do not use a network, embedded defaults, fixed percentile rank offsets, or legacy adapters. The bare digest of a calculation/report provided by the caller has no effect.

The default is finish --format markdown, and only the report path returned in its JSON is read. When needed and the capability exists, use finish --format docx instead. If DOCX capability is missing, retain Markdown and degrade with exit code 3; do not install dependencies or forge files.

Include the following directly in the final answer:

1. Optimistic, neutral, and conservative percentile rank ranges, confidence level, and basis. For regular batch admissions, list the range and typical schools by Reach, Match, Safety, and Observation categories, and remind that the minimum admission score line is not equal to the hot major score line.
2. For each applicable pathway, select one of: "Primary target," "Key preparation," "Alternative," "Observation," or "Not recommended." Also select one of: "Already satisfied," "Partially satisfied," "Not yet satisfied," "Pending verification," or "Not applicable." Explain the opportunities, challenges, personal fit, gaps, timeline, and constraints for each pathway. Do not just say "can pay attention" or "it depends on the situation."
3. List 3–7 "most urgent things to do now" first, then a full plan. Prioritize by time and value, and include completion criteria, the cost of not doing it, dependencies, evidence status, and the corresponding pathway or school.
4. Next to every number and policy, disclose the source, evidence status, coverage, and uncertainty. The report must uniformly display reference, inferred, partial, conflict, missing, masked, as well as coverage, method, and bounds.

Write the following disclaimer at both the beginning and end of the report: "This result is compiled by AI based on public data, intended solely as reference for academic planning and does not constitute an admission promise or formal academic advice. Policies, enrollment plans, and admission results are subject to the final publications of the relevant authorities and admitting institutions for the current year." Keep the output anonymous, deterministic, and path‑neutral. Publish exclusively/atomically to prevent overwrites. Do not publish, upload, or push any outputs without explicit user authorization.

Completion criteria: The report contains typical schools, pathway decisions, priority actions, and item‑by‑item evidence traces, and only references the current session's snapshot.

Recovery & Degradation

When the tool call has not killed the process, use the facade's next to check the stage. After a process death or host restart, run next, ingest, unavailable, or finish again with the original --workspace and --session. The facade's PlanningWorkflow.resume internally calls journal.load(session_id), using PlanningSessionReplayContext as the only recovery context, and the context methods complete finalize_evidence, calculate, and publish. The status snapshot, session digest, manifest digest, or JSON reconstructed by the caller cannot restore a completed receipt or replace factory replay.

The host retains the same private journal and validated evidence bundle until publication is complete. If journal loading fails, stop advancing that relies on the receipt and issue a controlled degradation; do not re‑run authenticated steps from scratch, do not re‑ask the user for information, and do not make the user provide internal JSON, local paths, or file paths.

When the network is unavailable, still produce a partial version based on authenticated materials: use the most comparable public historical anchor or a clear school/joint exam anchor for percentile rank ranges; give directional content for typical schools and pathways but clearly mark the year, reference status, and gaps. If regular batch data is available but pathway policies are insufficient, give the regular batch first, and vice versa. Any failure is turned into a controlled degradation or an unavailable reason; do not write internal paths, stack traces, or student identity into the response.

Completion criteria: The session can continue from the last valid snapshot. All incomplete work, gaps, and degradations are visible to the user.