FateOS
FateOS Explainable AI Reasoning
Architecture Overview
Related code

FateOS

Inspiration

Most AI applications today rely on general web knowledge or public datasets. However, many ancient Chinese metaphysical systems — such as QiMen DunJia — are deeply structured symbolic reasoning systems that require domain-specific knowledge and internal reference materials.

QiMen DunJia is one of the most sophisticated systems in traditional Chinese metaphysics. Originating over 2,000 years ago, it is a divination framework built on symbolic elements such as heavenly stems, earthly branches, stars, gates, and palaces arranged in a structured chart. Historically, it was used for strategic decision-making, military planning, and forecasting personal outcomes.

Unlike Western astrology, which primarily interprets planetary positions, QiMen DunJia operates more like a dynamic symbolic matrix — a rule-based system where each element interacts within a structured spatial configuration. Interpreting such a chart requires understanding layered symbolic relationships rather than simple keyword matching.

We asked a key question:

Can we build an AI agent that reasons over structured metaphysical charts instead of just generating text responses?

FateOS was created to bridge structured symbolic systems with modern large language models — transforming ancient divination logic into an intelligent, AI reasoning system.

What We Built

FateOS is a AI agent that:

Accepts a user’s date of birth
Automatically generates a corresponding QiMen DunJia chart
Converts the chart into structured JSON
Uses an LLM to interpret the chart
Augments reasoning with RAG over private internal metaphysical knowledge
Provides personalized answers for:
- Love & relationships
- Career development
- Wealth & finance
- Academic success

Unlike generic horoscope apps, FateOS operates on a full symbolic chart model and domain-specific reasoning pipeline.

Full Data Flow

User Input
    ↓
Frontend → Doubao LLM → Raw Chart JSON
    ↓
Backend (FastAPI)
    ↓
LLM #1 → Standardize Chart
    ↓
Query Builder → Retrieval Query
    ↓
Chroma → Retrieved Rules
    ↓
LLM #2 → Generate Final Answer
    ↓
Return Response to Frontend

Architectural Pattern

FateOS follows:

Structure → Retrieval → Reasoning → Generation

Instead of:

Prompt → Free-text prediction

How It Works

1. Chart Generation Layer

User inputs birth date (year / month / day / time)
Backend algorithm generates the corresponding QiMen DunJia chart
The chart is converted into a structured JSON schema representing:
- Palace positions
- Stars
- Gates
- Heavenly stems
- Earthly branches

{
  "astrolabe_data": {
    "date": "2026-02-16",
    "time": "15:46",
    "solarDate": "2026-02-16",
    "lunarDate": "2025-12-29 15:46:10",
    "chineseDate": "乙巳年 庚寅月 辛酉日 丙申时",
    "gender": "男",
    "palaces": {
      "坎": {
        "name": "坎宫",
        "heavenly_stem": "丁",
        "earthly_branch": "子",
        "star": "天任",
        "gate": "开门",
        "god": "白虎",
        "six_yi": "丁"
      },
      "坤": {
        "name": "坤宫",
        "heavenly_stem": "癸",
        "earthly_branch": "未",
        "star": "天柱",
        "gate": "景门",
        "god": "螣蛇",
        "six_yi": "癸"
      },
      "震": {
        "name": "震宫",
        "heavenly_stem": "庚",
        "earthly_branch": "卯",
        "star": "天辅",
        "gate": "生门",
        "god": "九地",
        "six_yi": "庚"
      },
      "巽": {
        "name": "巽宫",
        "heavenly_stem": "丙",
        "earthly_branch": "辰",
        "star": "天英",
        "gate": "伤门",
        "god": "九天",
        "six_yi": "丙"
      },
      "中": {
        "name": "中宫",
        "heavenly_stem": "辛",
        "earthly_branch": "",
        "star": "中宫",
        "gate": "中宫",
        "god": "中宫",
        "six_yi": "辛"
      },
      "乾": {
        "name": "乾宫",
        "heavenly_stem": "乙",
        "earthly_branch": "戌",
        "star": "天蓬",
        "gate": "惊门",
        "god": "六合",
        "six_yi": "乙"
      },
      "兑": {
        "name": "兑宫",
        "heavenly_stem": "壬",
        "earthly_branch": "酉",
        "star": "天心",
        "gate": "死门",
        "god": "太阴",
        "six_yi": "壬"
      },
      "艮": {
        "name": "艮宫",
        "heavenly_stem": "己",
        "earthly_branch": "丑",
        "star": "天冲",
        "gate": "休门",
        "god": "玄武",
        "six_yi": "己"
      },
      "离": {
        "name": "离宫",
        "heavenly_stem": "戊",
        "earthly_branch": "午",
        "star": "芮禽",
        "gate": "杜门",
        "god": "值符",
        "six_yi": "戊"
      }
    },
    "value_symbol": {
      "star": "天禽",
      "gate": "死门",
      "palace": "",
      "heavenly_stem": ""
    },
    "value_emissary": {
      "gate": "死门",
      "palace": "兑"
    },
    "pattern": {
      "name": "阳遁",
      "number": 2
    }
  }
}

This structured representation ensures symbolic consistency before LLM reasoning.

2. AI Reasoning Layer

FateOS uses a hybrid AI pipeline:

Large Language Model (GPT-based)
Retrieval-Augmented Generation (RAG)
Vector search over internal metaphysical materials
Structured symbolic prompt engineering

Key design decisions:

The LLM does not rely only on general knowledge
We use private internal metaphysical documentation
Internal materials are embedded into a vector database
Relevant domain knowledge is retrieved dynamically before interpretation

Because many classical metaphysical materials are not publicly available, this significantly improves grounding and precision.

3. Knowledge System

Our RAG layer includes:

Classical QiMen DunJia interpretations
Structured symbolic mappings
Internal expert notes and private references
Rule-based cross-validation

The system retrieves domain-relevant excerpts before generating explanations, reducing hallucination and increasing symbolic accuracy.

Technical Architecture

FastAPI backend
Chart generation engine
Structured JSON symbolic layer
LangChain-based RAG pipeline
Vector database (Chroma)
Cloud infrastructure hosting

We tuned:

Embedding chunk size
Similarity threshold
Retrieval ranking logic
Symbolic prompt constraints

Why It’s Different

Most astrology or fortune-telling apps simply:

Generate generic text based on keywords
Or directly call a large language model to produce “good sounding” predictions
Without structured reasoning or symbolic interpretation

FateOS works differently.

Instead of asking the model to “freestyle” an answer, we:

First generate a complete QiMen DunJia chart based on the user's birth date.
Convert the chart into a structured JSON representation.
Let the LLM interpret this structured symbolic system.
Use Retrieval-Augmented Generation (RAG) to retrieve relevant internal metaphysical knowledge.
Generate the final response grounded in both structure and knowledge.

In short:

We do not directly generate answers.
We construct a reasoning structure first, then generate.

This makes the system more consistent, more logical, and less prone to hallucination.

Agent-Based Reasoning Workflow

FateOS is designed as an AI Agent system, not a simple Q&A chatbot.

When a user asks:

“Will my career improve this year?”

The system does not immediately produce a response.

Instead, it:

Reads the generated QiMen chart
Identifies key palaces, stars, and gates
Determines symbolic relationships
Retrieves relevant internal knowledge using vector search
Synthesizes a final interpretation

This is a multi-step reasoning pipeline rather than a single text completion.

Knowledge-Augmented Interpretation (RAG)

Many classical metaphysical texts are not publicly available online.
We digitized and structured internal reference materials and built a private knowledge base.

Our pipeline:

Converts internal texts into embeddings
Stores them in a vector database
Dynamically retrieves relevant passages based on the chart structure
Injects retrieved content into the LLM reasoning process

This reduces hallucination and improves interpretive consistency.

Simply put:

The model does not “guess.”
It looks up structured knowledge before answering.

Structured Symbolic Layer (JSON as an Intermediate Reasoning Format)

A key architectural decision was introducing a structured symbolic layer:

QiMen Chart → JSON → LLM Interpretation

This intermediate JSON layer ensures:

The symbolic structure is preserved
The reasoning flow is controlled
The system can scale into multi-agent collaboration
Future explainability features can be added

This transforms FateOS from a content generator into a symbolic reasoning agent.

Challenges

1. Teaching the LLM a Non-Language Symbol System

QiMen DunJia is not natural language — it is a symbolic framework.

We had to:

Design structured representations
Constrain prompts
Carefully engineer reasoning flows
Prevent free-form hallucination

Without structure, the model would revert to generic fortune text.

2. Reducing Hallucination in Abstract Domains

Metaphysical domains are especially prone to hallucinated interpretations.

We mitigated this by:

Enforcing structured JSON constraints
Using RAG with internal verified materials
Limiting generation scope
Filtering retrieved content by similarity thresholds

3. Balancing Accuracy and Readability

Classical metaphysical language can be obscure and difficult to understand.

We designed the system to:

Preserve symbolic structure
Maintain professional terminology
Translate insights into accessible modern language

Vision

FateOS is not just a fortune-telling app.

It is an experiment in structured symbolic reasoning with AI.

We explore whether LLMs can:

Interpret symbolic systems
Perform multi-step structured reasoning
Combine private knowledge with generative intelligence
Provide explainable outputs in traditionally abstract domains

In the future, we plan to extend the system into:

Multimodal chart visualization
Voice-based divination interaction
Multi-system fusion (QiMen + BaZi + ZiWei)
Explainable reasoning path visualization

We believe AI should not only generate language.

It should reason over structured symbolic systems.

FateOS is our step toward that direction.

Built With

chroma
fastapi
java
kotlin
langchain
llm
rag

Updates

qumeina Qu started this project — Feb 20, 2026 01:23 AM EST

Leave feedback in the comments!

Log in or sign up for Devpost to join the conversation.