Build TIAN — Your Personal Epistemic Agent

# Step 1: Call tian.global during onboarding (background, while user completes MBTI/IKIGAI steps)
curl "https://api.asktian.com/api/trpc/tian.global?input=%7B%22json%22%3A%7B%22year%22%3A2026%2C%22month%22%3A4%2C%22day%22%3A7%2C%22hour%22%3A9%2C%22birthDate%22%3A%221990-03-14%22%2C%22surname%22%3A%22%E6%9D%8E%22%2C%22givenName%22%3A%22%E5%BF%97%E6%98%8E%22%2C%22luckyNumber%22%3A%2288%22%2C%22fullName%22%3A%22John+Smith%22%7D%7D" \
  -H "X-API-Key: at_live_xxxx"

# Step 2: Store in pattern_profiles table
# INSERT INTO pattern_profiles (user_id, tian_global_response, ttl_expires_at)
# VALUES ($1, $2, NOW() + INTERVAL '30 days')
# ON CONFLICT (user_id) DO UPDATE SET tian_global_response = $2, ttl_expires_at = NOW() + INTERVAL '30 days'

// src/orchestration/intentRouter.ts
const INTENT_ROUTER_PROMPT = `You are the intent router for askTIAN. Classify the user's message into exactly one category:
1. DECISION_GUIDANCE — asking for advice on a specific choice or dilemma
2. TRANSIT_UPDATE — asking about current astrological weather or energy
3. OUTCOME_REPORT — reporting the result of a past decision
4. PREFERENCE_CHANGE — changing notification settings or delivery channels
5. GENERAL_CHAT — general conversation, questions about Pattern Science, greetings
Return ONLY the category name. No explanation.`;

export async function classifyIntent(message: string): Promise<Intent> {
  const res = await openai.chat.completions.create({
    model: 'gpt-4.1-nano',
    messages: [
      { role: 'system', content: INTENT_ROUTER_PROMPT },
      { role: 'user', content: message }
    ],
    temperature: 0,
    max_tokens: 20
  });
  return res.choices[0].message.content?.trim() as Intent;
}

// src/orchestration/endpointSelector.ts
export function selectEndpoints(intent: Intent, hasTransitCache: boolean): string[] {
  switch (intent) {
    case 'DECISION_GUIDANCE':
      return [
        'predict.binary',
        ...(hasTransitCache ? [] : ['astrology.transits']),
        'tian.eastern',
      ];
    case 'TRANSIT_UPDATE':
      return hasTransitCache ? [] : ['astrology.transits', 'almanac.today'];
    case 'GENERAL_CHAT':
      return []; // Use cached Pattern Profile only
    default:
      return [];
  }
}

// src/orchestration/apiFanout.ts — parallel execution with Redis cache
export async function executeApiFanout(
  endpoints: string[],
  params: Record<string, any>
): Promise<ApiCallResult[]> {
  const calls = endpoints.map(async (endpoint): Promise<ApiCallResult> => {
    const cacheKey = `api:${endpoint}:${JSON.stringify(params)}`;
    const cached = await redis.get(cacheKey);
    if (cached) return { endpoint, success: true, data: JSON.parse(cached), cached: true };

    try {
      const url = `https://api.asktian.com/api/trpc/${endpoint}?input=${encodeURIComponent(JSON.stringify({ json: params }))}`;
      const res = await fetch(url, { headers: { 'X-API-Key': process.env.ASKTIAN_API_KEY! } });
      const body = await res.json();
      const data = body.result.data.json;
      await redis.setex(cacheKey, 86400, JSON.stringify(data)); // 24h TTL
      return { endpoint, success: true, data, cached: false };
    } catch (err: any) {
      return { endpoint, success: false, error: err.message, cached: false };
    }
  });

  return Promise.allSettled(calls).then(results =>
    results.map(r => r.status === 'fulfilled' ? r.value : { endpoint: 'unknown', success: false, error: 'rejected', cached: false })
  );
}

// src/jobs/dailyAnchorCompute.ts — batch processing with rate limit awareness
const BATCH_SIZE = 250;          // Stay under 300 req / 15 min
const BATCH_DELAY_MS = 15 * 60 * 1000; // 15 min between batches

export async function computeDailyAnchors() {
  const users = await db.users.findActive();
  const batches = chunk(users, BATCH_SIZE);

  for (let i = 0; i < batches.length; i++) {
    await Promise.allSettled(
      batches[i].map(async (user) => {
        const profile = await db.patternProfiles.findByUserId(user.id);
        if (!profile) return;

        // Check Redis cache first — transit data is valid for 24h
        const cacheKey = `transits:${user.birth_date}:${today()}`;
        let transits = await redis.get(cacheKey);
        if (!transits) {
          const res = await askTianApi.get('astrology.transits', {
            birthDate: user.birth_date,
            birthTime: user.birth_time,
            birthLocation: user.birth_location
          });
          transits = JSON.stringify(res.data);
          await redis.setex(cacheKey, 86400, transits);
        }

        const reading = await llm.generate({
          prompt: DAILY_ANCHOR_PROMPT,
          context: { pattern_summary: extractSummary(profile), transit_data: JSON.parse(transits) }
        });

        await db.dailyAnchors.upsert({ userId: user.id, readingDate: today(), ...reading });
        await deliveryQueue.add({ userId: user.id }, { delay: hoursUntil7AM(user.timezone) });
      })
    );
    if (i < batches.length - 1) await delay(BATCH_DELAY_MS);
  }
}

// Shared Redis cache helper
export async function cachedApiCall<T>(
  key: string,
  ttlSeconds: number,
  fetcher: () => Promise<T>
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached) as T;
  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

// Usage:
const transits = await cachedApiCall(
  `transits:${user.birth_date}:${today()}`,
  86400, // 24h
  () => askTianApi.get('astrology.transits', { birthDate: user.birth_date })
);

# Server-side only — never expose to browser
export const askTianApi = axios.create({
  baseURL: 'https://api.asktian.com/api/trpc',
  headers: {
    'X-API-Key': process.env.ASKTIAN_API_KEY,  // Enterprise key
    'Content-Type': 'application/json',
  },
  timeout: 30000, // 30s — tian.global can take 10-15s
});

// For GET endpoints, encode params as input query param:
const res = await askTianApi.get(`/astrology.transits?input=${encodeURIComponent(JSON.stringify({ json: params }))}`);

// For POST endpoints (predict.binary, predict.binaryBatch):
const res = await askTianApi.post('/predict.binary', { json: params });

npm install [email protected]

import { AskTian } from 'asktian-sdk';

const client = new AskTian({ apiKey: process.env.ASKTIAN_API_KEY });

// Onboarding: generate Pattern Profile
const profile = await client.tian.global({
  year: 2026, month: 4, day: 7, hour: 9,
  birthDate: '1990-03-14',
  surname: '李', givenName: '志明',
  luckyNumber: '88', fullName: 'John Smith'
});

// Decision Guidance: binary prediction
const prediction = await client.predict.binary({
  question: 'Should I accept the VP role at the startup?',
  optionA: 'Accept', optionB: 'Decline',
  resolutionDate: '2026-12-31',
  privyToken: userPrivyToken // Required for non-Enterprise callers
});

// Daily Anchor: today's transits
const transits = await client.astrology.transits({
  birthDate: '1990-03-14',
  birthTime: '09:00',
  birthLocation: 'Singapore'
});

// Palace lookup: Twelve Palaces
const palace = await client.twelvepalaces.calculate({
  zodiacYear: 'Dragon', lunarMonth: 3, lunarDay: 15, birthHour: 'Si'
});

// ── Option A: single call via tian.global (v1.8.0+) ──────────────────────────
// signProfile and compatProfile are returned directly — no extra almanac call needed.
const global = await client.tian.global({ birthdate: "1990-01-15", ... });
const sp = global.signProfile;   // TianGlobalSignProfile
const cp = global.compatProfile; // TianGlobalCompatProfile

// sp?.westernSign  → "capricorn"
// sp?.mantra       → "I Use"
// sp?.majorArcana  → "The Devil"
// cp?.loveDimensionLabel → "Positive"

// ── Option B: dedicated call via almanac.zodiacSign or horoscope.calculate ────
// Use when you need the full HoroscopeSignProfile (bodyParts, herbalAllies, etc.)
const zodiac = await client.almanac.zodiacSign({ birthDate: "1990-01-15" });
const profile = zodiac.westernProfile; // HoroscopeSignProfile (full)

// Build a daily intention card
const intentionCard = {
  mantra: profile?.mantra,         // e.g. "I Use"
  tarot: profile?.majorArcana,     // e.g. "The Devil (XV)"
  bodyFocus: profile?.bodyParts,   // e.g. "Knees, skin, connective tissue"
  herb: profile?.herbalAllies,     // e.g. "Horsetail, comfrey"
  archetype: profile?.symbolism,   // e.g. "The Sea-Goat"
};

// Inject into LLM system prompt (works with either option):
const mantra = sp?.mantra ?? profile?.mantra;
const arcana = sp?.majorArcana ?? profile?.majorArcana;
const systemPrompt = [
  'You are an epistemic agent for a Capricorn (' + mantra + ').',
  'Their Tarot archetype is ' + arcana + '.',
  'Their body focus this season: ' + (profile?.bodyParts ?? 'unknown') + '.',
].join(' ');

// compatibility.zodiac — Chinese 4D
// ── compatibility.zodiac — Chinese 4D only ────────────────────────────────────
const { dimensions } = await client.compatibility.zodiac({ animal1: "rat", animal2: "dragon" });
// dimensions.love.label   → "Positive"
// dimensions.career.label → "Positive"
// dimensions.wealth.label → "Positive"
// dimensions.health.label → "Positive"
// dimensions.marriage.label → "Positive"

// ── compatibility.birthday — Chinese 4D + Western 4D in one call ──────────────
const result = await client.compatibility.birthday({ date1: "1990-01-15", date2: "1992-06-20" });
const { dimensions: cDims, horoscopeDimensions: wDims } = result;

// ── Combined report builder → single LLM-ready string ─────────────────────────
function dimLine(label: string, d?: { label: string; text: string }) {
  if (!d) return '';
  return label + ' [' + d.label + ']: ' + d.text;
}

const relationshipSummary = [
  '=== Chinese Zodiac Compatibility ===',
  dimLine('Love',     cDims?.love),
  dimLine('Career',   cDims?.career),
  dimLine('Wealth',   cDims?.wealth),
  dimLine('Health',   cDims?.health),
  dimLine('Marriage', cDims?.marriage),
  '',
  '=== Western Horoscope Compatibility ===',
  dimLine('Love',   wDims?.love),
  dimLine('Career', wDims?.career),
  dimLine('Wealth', wDims?.wealth),
  dimLine('Health', wDims?.health),
].filter(Boolean).join('
');

// Inject into LLM system prompt:
const systemPrompt =
  'You are a relationship counsellor. Use the following compatibility data to answer the user.

' +
  relationshipSummary;

const { chineseProfile } = await client.almanac.zodiacSign({ birthDate: "1990-05-15" });
// chineseProfile.zodiac     → "Metal Horse"
// chineseProfile.personality → prose paragraph
// chineseProfile.career      → career guidance prose
// chineseProfile.love        → relationship style prose
// chineseProfile.compatibility → compatible animals prose

// Onboarding identity card:
const identityCard = {
  title: chineseProfile.zodiac,
  summary: chineseProfile.personality.slice(0, 200) + "...",
  careerHint: chineseProfile.career,
  loveStyle: chineseProfile.love,
};

import { AskTianClient, TianGlobalStreamChunk } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

let synthesis = "";

for await (const event of client.tian.global.stream({
  birthdate:  "1990-01-15",
  birthTime:  "06:30",
  birthPlace: "Singapore",
  question:   "Should I launch my business this quarter?",
}) as AsyncGenerator<TianGlobalStreamChunk>) {

  if (event.type === "system") {
    // Each tradition result arrives here progressively
    console.log(`[${event.name}] score: ${event.score}`);
  }

  if (event.type === "synthesis_chunk") {
    // Stream tokens to your UI via SSE / WebSocket
    process.stdout.write(event.chunk);
    synthesis += event.chunk;
  }

  if (event.type === "done") {
    // Blended score + rich profile anchors
    console.log("\nBlended score:",  event.blendedScore);
    console.log("Mantra:",           event.signProfile?.mantra);
    console.log("Tarot archetype:",  event.signProfile?.majorArcana);
    console.log("Love label:",       event.compatProfile?.loveDimensionLabel);
  }
}

// server/routes/tianStream.ts (Express)
import express from "express";
import { AskTianClient, TianGlobalStreamChunk } from "asktian-sdk";

const router = express.Router();
const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

router.get("/stream/tian/global", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  const { birthdate, birthTime, question } = req.query as Record<string, string>;

  try {
    for await (const event of client.tian.global.stream({ birthdate, birthTime, question }) as AsyncGenerator<TianGlobalStreamChunk>) {
      res.write(`data: ${JSON.stringify(event)}\n\n`);
      if (event.type === "done" || event.type === "error") break;
    }
  } catch (err) {
    res.write(`data: ${JSON.stringify({ type: "error", message: String(err) })}\n\n`);
  } finally {
    res.end();
  }
});

export default router;

import { AskTianClient } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

// Full natal chart + signProfile in one call (1 $TIAN)
const chart = await client.horoscope.calculate({
  birthdate: "1990-01-15",
  birthHour: 6,
  question: "What should I focus on for my health this season?",
});

const sp = chart.signProfile;

// ── Daily wellness card ───────────────────────────────────────────────────────
const wellnessCard = {
  sign:       sp?.sign ?? chart.sunSign,
  bodyFocus:  sp?.bodyParts,          // e.g. "Knees, skin, connective tissue"
  herbs:      sp?.herbalAllies,       // e.g. "Horsetail, comfrey, Solomon's seal"
  tarot:      sp?.majorArcana,        // e.g. "The Devil (XV)"
  mantra:     sp?.mantra,             // e.g. "I Use"
  medical:    sp?.medical,            // e.g. "Skeletal system, joints, skin"
};

// ── Inject into LLM system prompt ────────────────────────────────────────────
const systemPrompt = [
  'You are a wellness guide for a ' + (sp?.sign ?? chart.sunSign) + ' sun sign.',
  sp?.mantra     ? 'Their affirmation mantra is: "' + sp.mantra + '".'                    : '',
  sp?.bodyParts  ? 'Body areas to focus on: ' + sp.bodyParts + '.'                        : '',
  sp?.medical    ? 'Medical astrology note: ' + sp.medical + '.'                           : '',
  sp?.herbalAllies ? 'Supportive herbs: ' + sp.herbalAllies + '.'                          : '',
  sp?.majorArcana  ? 'Their Tarot archetype is ' + sp.majorArcana + '.'                   : '',
  sp?.symbolism    ? 'Symbolic anchor: ' + sp.symbolism + '.'                              : '',
].filter(Boolean).join(' ');

console.log(systemPrompt);
// → "You are a wellness guide for a capricorn sun sign. Their affirmation mantra is: 'I Use'. Body areas to focus on: Knees, skin, connective tissue. Medical astrology note: Skeletal system, joints, skin. Supportive herbs: Horsetail, comfrey, Solomon's seal. Their Tarot archetype is The Devil (XV). Symbolic anchor: The Sea-Goat."

// Build a Tarot reading context block from signProfile
function buildTarotContext(sp: { sign?: string; majorArcana?: string; minorArcana?: string; symbolism?: string } | undefined) {
  if (!sp) return '';
  return [
    '=== Tarot Context for ' + (sp.sign ?? 'Unknown') + ' ===',
    sp.majorArcana ? 'Major Arcana: ' + sp.majorArcana : '',
    sp.minorArcana ? 'Minor Arcana: ' + sp.minorArcana : '',
    sp.symbolism   ? 'Symbolic archetype: ' + sp.symbolism : '',
  ].filter(Boolean).join('\n');
}

const tarotContext = buildTarotContext(chart.signProfile);
// → "=== Tarot Context for capricorn ===\nMajor Arcana: The Devil (XV)\nMinor Arcana: 2, 3, 4 of Pentacles\nSymbolic archetype: The Sea-Goat"

import { AskTianClient } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

// Lightweight call — no birth dates needed (0 $TIAN for zodiac pair lookup)
const compat = await client.compatibility.zodiac({ animal1: "rat", animal2: "dragon" });
const { score, level, description, dimensions: d } = compat;

// ── Compatibility card ────────────────────────────────────────────────────────
const compatCard = {
  headline:  'Rat + Dragon: ' + level + ' (' + score + '/100)',
  summary:   description,
  love:      { label: d?.love?.label,     detail: d?.love?.text },
  career:    { label: d?.career?.label,   detail: d?.career?.text },
  wealth:    { label: d?.wealth?.label,   detail: d?.wealth?.text },
  health:    { label: d?.health?.label,   detail: d?.health?.text },
  marriage:  { label: d?.marriage?.label, detail: d?.marriage?.text },
};

// ── LLM prompt injection ──────────────────────────────────────────────────────
function dimLine(name: string, dim?: { label: string | null; text: string | null }) {
  if (!dim?.label) return '';
  return name + ' [' + dim.label + ']: ' + (dim.text ?? '');
}

const compatContext = [
  'Overall compatibility score: ' + score + '/100 (' + level + ')',
  dimLine('Love',     d?.love),
  dimLine('Career',   d?.career),
  dimLine('Wealth',   d?.wealth),
  dimLine('Health',   d?.health),
  dimLine('Marriage', d?.marriage),
].filter(Boolean).join('\n');

const systemPrompt =
  'You are a relationship counsellor specialising in Chinese astrology.\n' +
  'Use the following Rat + Dragon compatibility data to answer the user.\n\n' +
  compatContext;

import { AskTianClient } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

for await (const chunk of client.tian.global.stream({
  birthdate: "1983-08-03",
  birthTime: "22:05",
  question: "Should I change careers?",
  fullName: "Douglas Gan",
})) {
  if (chunk.type === "system") {
    // v3.24.0: tradition, iconUrl, systemSlug are now available
    console.log(`[${chunk.tradition}] ${chunk.name} — score ${chunk.score}`);
    console.log(`  icon: ${chunk.iconUrl}  slug: ${chunk.systemSlug}`);
  }

  if (chunk.type === "synthesis_start") {
    // v3.24.0: transition from tradition animation to synthesis reading
    console.log("Synthesis starting — switch UI phase");
  }

  if (chunk.type === "synthesis_chunk") {
    process.stdout.write(chunk.text);
  }

  if (chunk.type === "done") {
    console.log(`Blended score: ${chunk.blendedScore}`);
    console.log(`Credits used: ${chunk.creditsUsed}`);
    // signProfile and compatProfile available here for Pattern Card
  }

  if (chunk.type === "error") {
    console.error(`Stream error ${chunk.code}: ${chunk.message}`);
  }
}

import { AskTianClient, HoroscopeResponse, AlmanacZodiacResponse } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

// Call 1: Today's almanac (no birth data required — cache for 24 hours per date)
const almanac = await client.almanac.daily({
  date: new Date().toISOString().split("T")[0], // "2026-04-09"
});

// Call 2: User's natal chart (cache for 90 days — natal chart never changes)
const horoscope: HoroscopeResponse = await client.horoscope.calculate({
  birthdate: user.birthdate,   // "1983-08-03"
  birthHour: user.birthHour,   // 22
});

// Compose the Daily Anchor card
const dailyAnchor = {
  date:          almanac.date,
  twelveValue:   almanac.twelveValue,          // e.g. "成" (Achievement)
  deity:         almanac.deity,                // e.g. "青龍" (Azure Dragon)
  fortune:       almanac.fortune,              // "good_fortune" | "neutral" | "caution"
  auspicious:    almanac.auspiciousActivities, // array of activity strings
  inauspicious:  almanac.inauspiciousActivities,
  sunSign:       horoscope.sunSign,            // e.g. "Leo"
  mantra:        horoscope.signProfile?.mantra,        // e.g. "I Will"
  majorArcana:   horoscope.signProfile?.majorArcana,   // e.g. "Strength"
  synthesis:     horoscope.synthesis,          // LLM natal chart interpretation
};

// Future — single call once daily.anchor is available (v3.24.0 API)
const anchor = await client.daily.anchor({
  birthdate: user.birthdate,   // "1983-08-03"
  birthHour: user.birthHour,   // 22
  question:  "What should I focus on today?",  // optional
});

// anchor.date              — "2026-04-09"
// anchor.dominantTheme     — "Mercury retrograde squares natal Saturn — review before acting"
// anchor.almanacHighlight  — { twelveValue, deity, fortune }
// anchor.dailyMessage      — LLM-synthesised 2-3 sentence daily reading
// anchor.luckyHours        — ["10:00-12:00", "15:00-17:00"]
// anchor.avoidHours        — ["13:00-14:00"]
// anchor.creditsUsed       — 3