# OracleMind — Complete API Reference for AI Agents

> OracleMind is an AI-Powered Destiny Forecast platform that combines 5 modern AI agents with 5 ancient Chinese manuscripts (900-1800 CE) to predict life outcomes. Not fortune-telling — probability-based fore-sight.

## Quick Start for Agents

### 1. Free Prediction (No Auth Required)
```
GET /api/rate-limit
→ Check remaining free predictions

POST /api/simulate/personal/stream
Body: {"question": "Will I get a promotion this year?", "context": "I'm a software engineer at a mid-size company"}
→ SSE stream with 5 agent outputs + cross-validation
```

### 2. Bazi Calculation (Free)
```
POST /api/bazi/calculate
Body: {"year": 1990, "month": 6, "day": 15, "hour": 14}
→ Four Pillars chart with 10 gods, hidden stems, luck pillars
```

### 3. What-If Analysis (Free 1/IP)
```
POST /api/what-if
Body: {"question": "Should I change jobs?", "hypotheticalChange": "If I switch to a startup"}
→ Counterfactual timeline analysis
```

### 4. Daily Forecast (Registered Users)
```
GET /api/daily-forecast
Headers: Cookie: next-auth.session-token=xxx
→ Daily energy, luck areas, mystical message
```

### 5. Pricing Plans
```
GET /api/billing/plans
→ Free ($0, 5/day), Premium ($9.99/mo), Deep ($4.99/analysis)
```

## API Endpoints

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| /api/simulate/personal/stream | POST | Guest | Personal destiny forecast (SSE) |
| /api/simulate/event/stream | POST | Guest | Event prediction (SSE) |
| /api/what-if | POST | Guest | Counterfactual analysis |
| /api/bazi/calculate | POST | None | Four Pillars calculation |
| /api/daily-forecast | GET | Session | Daily forecast |
| /api/billing/plans | GET | None | Pricing plans |
| /api/referral | POST | Session | Referral rewards |
| /api/feedback/submit | POST | Guest | User feedback |
| /api/rate-limit | GET | None | Check remaining quota |
| /api/openapi.json | GET | None | OpenAPI 3.0 spec |

## The 5 Ancient Manuscripts

Each manuscript validates predictions from a unique perspective. Users don't see manuscript names — only the mystical validation results.

### 1. Yuanhai Ziping — "The Abyssal Ocean Manuscript" (960 CE)
- **Perspective**: Source pattern — traces any life event back to its cosmic origin
- **Mystical Power**: Reveals the "source code" written at the moment of first breath
- **Ritual**: Scholar burns sandalwood, faces North Star before reading

### 2. Ziping Zhenyuan — "True Commentary of the Purple Star" (1700s)
- **Perspective**: Formation strength — whether destiny ascends or crumbles
- **Mystical Power**: Identifies the "formation" — a hidden structure that determines greatness
- **Ritual**: Read by candlelight when moon is unseen

### 3. Sanming Tonghui — "Convergence of Three Destinies" (1500s)
- **Perspective**: Multi-dimensional — Heaven, Earth, Human dimensions simultaneously
- **Mystical Power**: Finds "convergence points" — rare windows where destiny can be rewritten
- **Ritual**: Hold three coins from three dynasties

### 4. Ditian Sui — "Marrow of Heaven's Drop" (1700s)
- **Perspective**: Energy flow — whether life energy is rising, falling, or blocked
- **Mystical Power**: Reads the "voltage of a soul" — detects destiny acceleration
- **Ritual**: Read at dawn with a drop of water on the page

### 5. Qiongtong Baojian — "Mirror of Seasonal Truths" (1700s)
- **Perspective**: Seasonal timing — spring (growth), summer (peak), autumn (harvest), winter (dormancy)
- **Mystical Power**: Identifies what "medicine" restores balance when season is wrong
- **Ritual**: Open to random page on first day of each season

## The 5 Modern AI Agents

| Agent | Role | Question Asked |
|-------|------|----------------|
| Strategist | Strategic analysis | "What factors influence this outcome?" |
| Data Scientist | Data-driven assessment | "What does historical data suggest?" |
| Guardian | Risk assessment | "What are the hidden dangers?" |
| Optimist | Opportunity identification | "What positive paths exist?" |
| Devil's Advocate | Contrarian analysis | "Why might this prediction fail?" |

## The 5×5 Cross-Validation Matrix

Each modern agent's output is validated against each ancient manuscript's perspective, producing a 25-cell matrix. The consensus score (0-100) indicates prediction reliability.

## Response Format

All predictions return:
```json
{
  "question": "string",
  "consensusScore": 0-100,
  "primaryOutcome": "string",
  "scenarios": [
    {"label": "Optimistic", "probability": 0.0-1.0, "reasoning": "string"},
    {"label": "Neutral", "probability": 0.0-1.0, "reasoning": "string"},
    {"label": "Conservative", "probability": 0.0-1.0, "reasoning": "string"}
  ],
  "crossValidation": {
    "classicalConsensus": 0-100,
    "modernConsensus": 0-100,
    "divergenceFlag": boolean
  },
  "agentTraces": [...],
  "baziSnapshot": {...}
}
```

## Rate Limits

| Tier | Limit | Price |
|------|-------|-------|
| Free | 5/day per IP, 15 total per IP | $0 |
| Premium | Unlimited L1+L2 | $9.99/month |
| Deep | 8-round deep analysis | $4.99/analysis |

## Authentication

- **Free tier**: NextAuth Guest mode (auto-generated UUID, no registration needed)
- **Premium tier**: NextAuth session with subscription validation
- **API access**: Cookie-based session (next-auth.session-token)

## Integration Examples

### Python
```python
import requests
response = requests.post(
    "https://oraclemind.cc/api/simulate/personal/stream",
    json={"question": "Will my startup succeed?"},
    stream=True
)
for line in response.iter_lines():
    print(line.decode())
```

### cURL
```bash
curl -X POST https://oraclemind.cc/api/bazi/calculate \
  -H "Content-Type: application/json" \
  -d '{"year": 1990, "month": 6, "day": 15, "hour": 14}'
```

## Contact
- Website: https://oraclemind.cc
- Email: support@oraclemind.cc
- API Docs: https://oraclemind.cc/api/openapi.json
- Agent Config: https://oraclemind.cc/ai-plugin.json