732642856
137 lines
11 KiB
Markdown
137 lines
11 KiB
Markdown
# Commercial Jyotish Invocation Optimization Plan
|
|
|
|
## Scope
|
|
|
|
This plan optimizes the commercial repository's actual Jyotish skill execution and the results returned to paying users. It does not modify, reorganize, or treat the research repository as a runtime dependency. Generic frontend, account, billing, and deployment work is out of scope unless it directly prevents an astrology capability from being invoked, verified, or truthfully surfaced.
|
|
|
|
## Verified Runtime Chain
|
|
|
|
```text
|
|
POST /api/consult
|
|
-> getJyotishAgent(model)
|
|
-> consultationTool / runConsultationWorkflow
|
|
-> POST ${JYOTISH_API_BASE}/api/consultation_workflow
|
|
-> JyotishHandler._compute_consultation_workflow
|
|
-> UnifiedConsultationOrchestrator route selection + strict workflow
|
|
-> chart/evidence/technique/dasha/oracle layers
|
|
-> consumer_context + auditable response
|
|
-> language model renders the bounded user answer
|
|
```
|
|
|
|
Other live product paths:
|
|
|
|
- Daily guidance: `frontend/src/app/api/daily-starlanguage/route.ts` -> Python `/api/chart` and daily guidance logic.
|
|
- Synastry: `frontend/src/app/api/synastry/route.ts` -> Python `/api/chart` for both charts and `/api/synastry`.
|
|
- Birth-time flows call the bounded guide/rectification routes and must not obtain unrestricted consultation authority.
|
|
|
|
Verified baseline:
|
|
|
|
- `python3 scripts/user_invocation_acceptance_check.py`: pass. Strict routes available: career, relationship, finance.
|
|
- Core API and external adapters are available; the official VedAstro snapshot is not ready in this environment (`fast_local_fallback`, premium key absent). This is an explicit degraded external layer, not a failed local calculation.
|
|
- `skills/jyotish-vedic-astrology/SKILL.md` exists and is the default Mastra skill path.
|
|
- The Python server has many registered endpoints, but only the paths above are currently commercial-user reachable. Registered-but-unreachable techniques are not treated as product capability.
|
|
|
|
## Non-Negotiable Product Truth Rules
|
|
|
|
1. A user-facing claim must originate from a computed invocation result, never from an LLM choosing to improvise chart facts.
|
|
2. For career, relationship, wealth, timing, health, or event claims, the returned evidence must contain the domain-required strict workflow layers and an explicit status for every missing layer.
|
|
3. The commercial response may simplify language, but it may not drop a `blocked`, `degraded`, conflict, ayanamsa/node-mode, Dasha-boundary, functional-benefic/malefic, or external-evidence limitation that materially changes the claim.
|
|
4. Local engine success, external-engine availability, executed raw coverage, parity, and predictive calibration remain separate states. No response upgrades one state into another.
|
|
5. No research checkout/path, raw private case, oracle credential, or unapproved source artifact becomes a commercial runtime dependency.
|
|
|
|
## Phase 0: Make Invocation Deterministic
|
|
|
|
### Problem
|
|
|
|
The chat agent receives instructions to call `consultationTool`, but model tool choice is probabilistic. An instruction-level requirement is not a server-side guarantee that a new chart claim has traversed the Jyotish engine.
|
|
|
|
### Work
|
|
|
|
1. Extract a deterministic `requiresJyotishWorkflow(question, profile, conversationState)` classifier in the commercial server layer.
|
|
2. For a new chart claim, call `runConsultationWorkflow` before streaming model output, then inject only the validated `consumer_context`/evidence projection into the agent. Do not depend on the model to decide whether to call the tool.
|
|
3. Preserve tool use for follow-ups only when the stored invocation result covers the request; otherwise re-run the workflow with an explicit reason.
|
|
4. Add an invocation receipt to the stream metadata: immutable request ID, workflow version, route, entry mode, local/external status, and evidence-packet ID. Never include birth data, question text, prompts, or secrets.
|
|
5. Define explicit `not_astrology`, `needs_profile`, `computed`, `degraded`, and `blocked` branches. Non-astrology conversation must not spend a calculation; incomplete birth data must not produce synthetic chart claims.
|
|
|
|
### Tests
|
|
|
|
- Contract tests prove career, relationship, wealth, and timing questions invoke `/api/consultation_workflow` exactly once before text is emitted.
|
|
- Follow-up reuse is allowed only for matching chart/configuration/version; differing birth data, reference date, ayanamsa, node mode, or required domain invalidates reuse.
|
|
- Model-mock tests prove a model cannot bypass a required invocation.
|
|
- Stream tests prove receipts contain no personal or secret fields.
|
|
|
|
## Phase 1: Enforce Route-Specific Skill Completeness
|
|
|
|
1. Create one versioned TypeScript schema for the commercial projection of the Python workflow response. Parse it in `frontend/src/mastra/index.ts`; reject malformed or incomplete results instead of passing untyped records to the model.
|
|
2. Build an executable route matrix from `SKILL.md`, strict-workflow contracts, and the technique registry. At minimum enforce:
|
|
- career: D10 + A10 and functional benefic/malefic;
|
|
- relationship: D9 + UL and functional benefic/malefic;
|
|
- wealth: D2/D11 and functional benefic/malefic;
|
|
- timing/event: Vimshottari + Narayana Dasha, required Dasha boundaries, transit status, and external-evidence status.
|
|
3. The API projection carries technique `used/not_used/blocked`, missing layers, conflict resolution, confidence boundary, and the raw-evidence identifiers required by the selected route.
|
|
4. Add a Python-to-TypeScript golden fixture for every route and every terminal status (`ready`, `degraded`, `blocked`). Fixtures must use public synthetic cases only.
|
|
5. Cross-check the frontend-reachable endpoint inventory against Python dispatch. Fail CI when a new user-reachable operation has no handler, no schema, or no capability contract.
|
|
|
|
### Tests
|
|
|
|
- Golden parity for route projection and error/status preservation.
|
|
- Negative tests delete each required layer and assert the commercial answer cannot make the corresponding claim.
|
|
- Endpoint reachability inventory test includes `/api/consultation_workflow`, daily guidance, synastry, and all birth-time routes.
|
|
|
|
## Phase 2: Truthful External-Oracle Degradation
|
|
|
|
1. Treat the current `fast_local_fallback` as a first-class execution state in the commercial response contract, not an incidental log value.
|
|
2. Map external layers independently: PyJHora/JHora comparison, jyotishganit, VedAstro official raw snapshot, parity status, and real-case calibration. Preserve license boundaries.
|
|
3. When a premium key or official snapshot is unavailable, retain local computation but force the exact affected conclusion to `degraded` or `blocked` according to the strict-workflow contract. Do not silently say an external check ran.
|
|
4. Add a configurable official-snapshot budget/timeout with a circuit state and sanitized telemetry. The fallback must be deterministic, bounded, and visible to audit metadata.
|
|
5. Add a deployment gate that runs the existing adapter diagnostics and a selected public-synthetic same-chart replay. It must report `unavailable`, `partial_verified`, and `mismatch` distinctly rather than failing open.
|
|
|
|
### Tests
|
|
|
|
- No-key, timeout, malformed-provider, parity-mismatch, and fully-available fixtures.
|
|
- Assertions that the language-model context never upgrades `partial_verified` to verified or hides a material blocked layer.
|
|
- License/attribution snapshot test for every enabled external adapter.
|
|
|
|
## Phase 3: Optimize Real Engine Cost And Reliability
|
|
|
|
1. Instrument only actual entrypoints (`consultation_workflow`, chart, synastry, daily guidance, high-rigor workflow) with sanitized elapsed-time spans: routing, ephemeris/chart, divisional charts, dasha, Shadbala/Ashtakavarga, external adapters, serialization.
|
|
2. Benchmark public synthetic charts by route/configuration on the production-equivalent 1-vCPU/2-GB budget. Establish p50/p95, response-size, timeout, and queue-depth budgets before caching or parallelization.
|
|
3. Memoize only immutable, configuration-keyed computation fragments. Use a bounded TTL/LRU keyed by a cryptographic digest of normalized input and computation settings; never cache raw profile data, user text, credentials, or final personalized prose.
|
|
4. Keep high-rigor/batch/external-heavy paths asynchronous when their measured p95 exceeds the interactive budget. Preserve existing job identity, polling, cancellation, and evidence-packet retrieval semantics.
|
|
5. Reduce model context to the route-required evidence projection. Full raw packets remain retrievable only through the authenticated/auditable path, avoiding token cost and accidental evidence loss in chat rendering.
|
|
|
|
### Tests
|
|
|
|
- Determinism before/after cache hit; ayanamsa/node-mode/reference-date changes must miss cache.
|
|
- Concurrent identical requests do not duplicate expensive work; cancellation never corrupts a shared result.
|
|
- Benchmark regression thresholds and response-shape snapshots.
|
|
|
|
## Phase 4: Wire Secondary Live Flows Into The Same Truth Contract
|
|
|
|
1. Daily guidance must carry reference date, transit source/configuration, local/external state, and a bounded claim scope; no generic model prose may replace chart-derived daily data.
|
|
2. Synastry must preserve both chart settings, Ashtakoot method/version, D9 evidence, relationship-route required layers, and non-comparability states.
|
|
3. Birth-time guidance/rectification remains evidence-collection and candidate-scoring only. It cannot present a candidate as a verified birth time until its configured evidence threshold and strict workflow state are met.
|
|
4. Use one commercial `AstrologyExecutionEnvelope` for the shared status/audit fields while retaining route-specific payloads. This is an adapter boundary, not a rewrite of engine formulas.
|
|
|
|
### Tests
|
|
|
|
- Daily date-boundary and fallback fixtures.
|
|
- Synastry settings mismatch/non-comparability fixtures.
|
|
- Rectification candidate confidence and no-premature-certainty fixtures.
|
|
|
|
## Phase 5: Commercial Capability Intake
|
|
|
|
When the owner approves a research-derived capability, add it only through a commercial intake manifest containing capability ID/version, approved interface, supplied source hash, license/attribution decision, input/output contract, privacy class, test fixture provenance, rollout flag, observability, and rollback path. The commercial adapter consumes that interface only; it does not import a research working tree.
|
|
|
|
## Execution Order
|
|
|
|
1. Reconcile local branch with upstream before editing runtime behavior.
|
|
2. Phase 0 deterministic invocation.
|
|
3. Phase 1 route-completeness schemas and golden contracts.
|
|
4. Phase 2 external-degradation truth handling.
|
|
5. Phase 3 measured engine performance/reliability.
|
|
6. Phase 4 secondary live flows.
|
|
7. Phase 5 only after an owner-approved capability handoff.
|
|
|
|
Each phase requires relevant Python + frontend tests, user-invocation acceptance, adapter diagnostics, production build, and `git diff --check`. Push/deploy needs separate owner authorization.
|