skjncs2026/zhidu-pa-agent

Zhidu (知渡) — PA_Agent Deterministic Decision Engine

Overview

Zhidu is an AI-powered college application guidance platform for Chinese Gaokao students. This repository demonstrates the core innovation: a PA_Agent deterministic decision engine that separates critical recommendation logic from LLM inference, ensuring auditable and reproducible recommendations.

Architecture: Hybrid Deterministic + LLM Pipeline

User Input (score / province / subject)
    │
    ▼
Gate Check (🔒 locked)         ── data sufficiency gate
    │
    ▼
Decision Trace (mixed auth)    ── typed decision nodes
    │
    ▼
Tier Classification (🔒 locked) ── RUSH / STABLE / SAFE
    │
    ▼
Continuity Guard               ── contradiction detection
    │
    ▼
Validation (4 layers)          ── structure/range/coherence/semantic
    │
    ▼
LLM Analysis Layer             ── personalized interpretation
    │
    ▼
Final Recommendation

Key Innovation: Typed Decision Authority

Traditional AI guidance systems delegate all decisions to LLMs, risking hallucination. Zhidu's PA_Agent architecture classifies decision nodes into three authority levels:

Authority	Symbol	Description	Example
Locked	🔒	Program authority, LLM cannot override	Data sufficiency, tier classification, probability calculation
Overridable	🔓	Program-first, LLM may override with evidence	Confidence assessment, sector allocation
AI-Primary	🤖	LLM-led, program provides fallback	Market commentary, personalized advice

This ensures the same input always produces the same data-matching result, while allowing LLM flexibility for interpretation and personalization.

Files

File	Description
app.py	Gradio demo application (requires PRO subscription for HF Spaces)
decision_engine.py	Core PA_Agent pipeline implementation in Python
requirements.txt	Python dependencies

Running Locally

pip install -r requirements.txt
python app.py

Then open http://localhost:7860 in your browser.

Design Patterns Referenced

This implementation draws from several research patterns:

• PA_Agent (two-stage deterministic + LLM hybrid decision architecture)
• Credal Transformer (uncertainty quantification for confidence scoring)
• Multi-signal voting (5-signal direction determination with threshold consensus)
• Continuity guard (contradiction detection across sequential recommendations)

Full Platform Tech Stack

The production Zhidu platform uses:

• Next.js 16 (App Router + Turbopack) + TypeScript
• Supabase (PostgreSQL + Auth + Realtime)
• @zhidu/ai package (decision engine + RAG + LLM + investment analysis)
• ML models (XGBoost + LightGBM ensemble for admission probability)
• DeepSeek V4 Pro via mydamoxing.cn (function calling + streaming)

Citation

If you use this work, please cite:

@software{zhidu_pa_agent_2026,
  title = {Zhidu: PA_Agent Deterministic Decision Engine for AI-Guided College Recommendations},
  author = {Song, Yangting},
  year = {2026},
  url = {https://huggingface.co/skjncs2026/zhidu-pa-agent}
}