# TRINETRA — Comprehensive Quantitative Doctrine, Architecture & Specification
> The Complete Analytical Reference Manual for AI Crawlers, Quantitative Research Agents, and Large Language Models.

Website: https://trinetra.trade
API Gateway: https://api.trinetra.trade
Brief Version: https://trinetra.trade/llms.txt
Platform Classification: Financial Research, Decision-Support, Quantitative Screening (Non-Execution)

---

## Table of Contents
1. Core Operating Doctrine & System Philosophy
2. Master Classical Doctrine Integration ([D], [L], [W], [C], [Wy])
3. Mathematical Formulations & Gate Specifications
4. The Eye: Multi-Horizon Breakout Screener Mechanics
5. Vishwa: Global Macro to India-Impact Forward Engine
6. Derivatives Room: Options Analytics & Institutional Smart Money
7. Grounded AI Architecture: "AI Narrates, Engine Decides"
8. API Endpoints, Request Formats, and Response Schemas
9. Legal & Execution Disclaimers

---

## 1. Core Operating Doctrine & System Philosophy

TRINETRA operates on a foundational mandate:
**"Do more work once, after market hours, and serve precomputed results efficiently to many users."**

### Institutional Reality of Trading Execution
TRINETRA is explicitly **not a broker or trade execution venue**. Users utilize TRINETRA to:
- Screen the universe of thousands of Indian equities (NSE/BSE).
- Identify institutional accumulation and high-probability breakout patterns.
- Inspect market regime state and thematic capital rotation.
- Formulate predefined entry triggers, position sizes, and invalidation stop levels.

All trade orders are manually executed by users through their respective SEBI-registered brokers (e.g., Zerodha, Upstox, Groww, Angel One). Consequently, TRINETRA prioritizes:
- **Mathematical Correctness**: Zero fabrication or guessing of price or financial figures.
- **Reproducibility**: Subpoena-grade deterministic auditability for every historical recommendation.
- **Execution Discipline**: Strict anti-chase rules preventing retail traders from entering extended moves.
- **Resource Efficiency**: High-performance indexed reads serving thousands of concurrent users with sub-10ms response times.

---

## 2. Master Classical Doctrine Integration

TRINETRA codifies over a century of proven tape reading and trend trading literature into automated, deterministic algorithmic gates:

### [D] Nicolas Darvas — The Box Method
- **Box Top**: Highest high established over at least 3 consecutive trading sessions without being violated.
- **Box Bottom**: Lowest low established during the same consolidation range without being breached.
- **Box Breakout**: Occurs exclusively when the closing price decisively breaks above the Box Top on expanding volume.
- **Trailing Stop Discipline**: Automatic trailing stop placed strictly 1 tick beneath the Box Bottom of the most recently established box.
- **Pyramiding**: Additional position sizing is permitted only as a stock enters a higher, new box range.

### [L] / [L5] / [L7] Jesse Livermore — Pivotal Points & Time Stops
- **Reversal Pivotal Point**: A structural shift in trend direction accompanied by a 50% to 500% increase in 50-day average daily volume.
- **Continuation Pivotal Point**: A tight consolidation pause inside an established trend; entries are triggered only after breakout on the strong side.
- **The Freshness Window (`_FRESH_WINDOW_PCT`)**: A breakout is considered fresh only if current price is within **5% to 8%** of the pivot. Buying beyond this threshold is classified as `CHASE_TRAP`.
- **>=3-Point Follow-Through Confirmation**: A genuine breakout must follow through within 3 to 5 bars; immediate stall indicates false breakout.
- **The Time Stop**: If an entered stock fails to produce meaningful momentum within 5 to 7 trading days ("Listless Drifter"), the position is flagged for exit at breakeven ("time is money").
- **Five Money Management Rules**:
  1. Probe in tranches (e.g., 20/20/20/40), adding only at higher prices.
  2. Maximum 10% hard stop loss determined prior to order placement.
  3. Maintain dedicated cash reserves during hostile market regimes.
  4. Cut losses ruthlessly; let winning trends run.
  5. Systematically bank 50% of windfall profits into cash reserves.

### [W] Stan Weinstein — Stage Analysis
- **Stage 1 (Basing)**: Neglected consolidation around a flattening 30-week (150/200 DMA) moving average. Volume dries up.
- **Stage 2 (Advancing / Breakout)**: Decisive breakout above base resistance on heavy volume (RVOL >= 2.0x), accompanied by an upward-sloping 30-week moving average. **This is the primary TRINETRA buy zone.**
- **Stage 3 (Topping / Distribution)**: Volatility expands, volume spikes on down days, moving average flattens. Churn and distribution prevail.
- **Stage 4 (Declining)**: Breakdown below support with downward-sloping 30-week moving average. Zero long entries permitted.
- **Mansfield Relative Strength (MRS)**: Calculation of outperformance vs benchmark index. A valid Stage 2 candidate must demonstrate positive and rising MRS.

### [C] Anna Coulling — Volume Price Analysis (VPA)
- **Effort vs Result Principle (Wyckoff's Third Law)**: Price spread (result) must correlate with volume (effort).
  - *Validation*: Wide spread up-bar on high volume -> Healthy institutional demand.
  - *Trap Up (`trap_up`)*: Wide spread up-bar on low volume -> Retail trap engineered by market makers.
  - *Churn (`churn`)*: Narrow spread up-bar on exceptionally high volume -> Insiders distributing shares into retail buying.
  - *Drying Volume*: Pullback on declining volume -> Lack of selling pressure, constructive flag.

### [Wy] Richard Wyckoff — Tape Reading & Structural Tests
- **Three Fundamental Laws**:
  1. Law of Supply and Demand.
  2. Law of Cause and Effect (horizontal consolidation size dictates vertical target).
  3. Law of Effort vs Result.
- **Rally-Retracement Filter**: A genuine counter-trend rally retraces 50% to 66% of the prior swing; shallow weak bounces represent continuation patterns for the dominant trend.
- **Natural Reaction Tolerance**: Pullbacks of 33% to 50% of the preceding up-leg on light volume are classified as normal digestion; premature stop-outs are filtered out.

---

## 3. Mathematical Formulations & Gate Specifications

### 3.1 Relative Volume (RVOL)
$$\text{RVOL}_t = \frac{V_t}{\frac{1}{N}\sum_{i=1}^{N} V_{t-i}}$$
Where:
- $V_t$ is the volume of current bar $t$.
- $N = 50$ trading sessions (baseline moving average).
- Institutional Breakout Threshold: $\text{RVOL}_t \ge 1.5$ (Preferred: $\ge 2.0$).

### 3.2 Mansfield Relative Strength (MRS)
$$R_t = \frac{P_{\text{stock}, t}}{P_{\text{benchmark}, t}}$$
$$\text{SMA\_R}_t = \frac{1}{M}\sum_{k=0}^{M-1} R_{t-k} \quad (M = 52 \text{ weeks or } 250 \text{ days})$$
$$\text{MRS}_t = \left( \frac{R_t}{\text{SMA\_R}_t} - 1 \right) \times 100$$
- Criteria: $\text{MRS}_t > 0$ and $\frac{d}{dt}\text{MRS}_t > 0$.

### 3.3 Anti-Chase Freshness Gate
$$\text{Extension} = \frac{P_{\text{current}} - P_{\text{pivot}}}{P_{\text{pivot}}}$$
- If $\text{Extension} < 0$: Pre-breakout / Setup phase.
- If $0 \le \text{Extension} \le 0.08$: **FRESH ENTRY ZONE** (Actionable).
- If $\text{Extension} > 0.08$: **CHASE TRAP** (Gated; entries forbidden).

### 3.4 Black-Scholes-Merton Options Analytics
For European index and stock derivatives on the National Stock Exchange (NSE):
$$d_1 = \frac{\ln(S/K) + (r - q + \frac{\sigma^2}{2})T}{\sigma\sqrt{T}}$$
$$d_2 = d_1 - \sigma\sqrt{T}$$
- **Delta ($\Delta$)**: $\frac{\partial V}{\partial S}$
- **Gamma ($\Gamma$)**: $\frac{\partial^2 V}{\partial S^2} = \frac{N'(d_1)e^{-qT}}{S\sigma\sqrt{T}}$
- **Theta ($\Theta$)**: Time decay per calendar day.
- **Vega ($\nu$)**: Sensitivity to implied volatility changes per 1% move in $\sigma$.

---

## 4. The Eye: Multi-Horizon Breakout Screener Mechanics

The Eye processes the NSE equity universe through a rigorous 7-tier funnel:

```
[Universe: ~2,200 NSE Equities]
                │
                ▼
  [Filter 1: Liquidity & Tradability]
  Median turnover >= ₹5 Crore; Circuit-filter immunity
                │
                ▼
  [Filter 2: Trend & Stage Filter]
  Close > 200 DMA; 200 DMA slope > 0; Mansfield RS > 0
                │
                ▼
  [Filter 3: Structural Pattern Discovery]
  Darvas Box Breakout / VCP Contraction / High Tight Flag
                │
                ▼
  [Filter 4: Volume & VPA Verification]
  RVOL >= 1.5x; No Churn / No Trap-Up anomalies
                │
                ▼
  [Filter 5: Anti-Chase Freshness Gate]
  Price <= 1.08 * Pivot Level
                │
                ▼
  [Filter 6: Multi-Factor Composite Scoring]
  Momentum + Volume Quality + Industry Rank + Delivery %
                │
                ▼
[The Daily Eye: Top 20 Ranked Candidates]
```

---

## 5. Vishwa: Global Macro to India-Impact Forward Engine

Vishwa is TRINETRA's macroeconomic synthesis engine. It connects international market shocks directly to Indian sectors:

### 5.1 The Macro Driver Matrix
| Driver | Ticker | Positive for India | Negative for India |
| :--- | :--- | :--- | :--- |
| **Brent Crude** | `BZ=F` | Price drop below $75/bbl (Curbing CAD & Inflation) | Spike above $85/bbl (Imports costlier, OMCs squeezed) |
| **US Dollar Index** | `DX-Y.NYB` | DXY weakness (<102) -> EM capital inflows | DXY strength (>105) -> FII outflows from Indian equities |
| **US 10Y Yield** | `^TNX` | Falling yields -> Risk-on appetite for emerging markets | Yield spike (>4.5%) -> Currency pressure & foreign selling |
| **S&P 500** | `^GSPC` | Bullish global equity trend support | Global liquidation / contagion risk |
| **Gold** | `GC=F` | Stable / mild growth | Parabolic spike (Systemic flight to safety / geopolitical risk) |

### 5.2 The Forward Spine (`Level` + `Trigger` + `Flow` + `Event`)
1. **Level**: Key technical support/resistance bands on Nifty 50 and Bank Nifty.
2. **Trigger**: Specific condition that confirms resumption or breakdown.
3. **Flow**: Daily net institutional buying/selling from FIIs (Foreign Institutional Investors) and DIIs (Domestic Institutional Investors).
4. **Event**: Upcoming high-impact macroeconomic catalysts (RBI MPC rate decisions, US Fed FOMC, Union Budget, CPI releases).

---

## 6. Derivatives Room: Options Analytics & Smart Money

The Derivatives Room evaluates the collective market positioning through quantitative option metrics:
- **Max Pain Theory**: Identifies the strike price where the greatest dollar value of outstanding options expires worthless, serving as a powerful gravitational magnet near Thursday weekly/monthly expiries.
- **Call and Put OI Walls**: Tracks the highest open interest strike concentrations, establishing definitive resistance ceilings and support floors.
- **Participant-wise Open Interest Breakdown**:
  - `FII`: Institutional foreign capital (Smart Money index futures long/short ratio).
  - `DII`: Domestic mutual funds and insurance capital.
  - `Pro`: Proprietary trading desks and market makers (gamma scalpers).
  - `Client`: Retail directional traders (often contrarian indicator at market extremes).

---

## 7. Grounded AI Architecture: "AI Narrates, Engine Decides"

TRINETRA uses generative AI strictly as a reasoning and communicative synthesis layer, never as an ungrounded generator of facts:

### Number-Provenance Guardrail
1. The deterministic quant engine generates the exact feature vector:
   ```json
   {
     "symbol": "NSE:TATAMOTORS",
     "close": 985.40,
     "pivot": 950.00,
     "rvol": 2.34,
     "stage": 2,
     "mrs_nifty": 14.2,
     "stop_loss": 928.00
   }
   ```
2. The LLM receives this feature vector with strict instruction constraints:
   - Every number mentioned in the generated thesis must exist in the input vector.
   - Any hallucination of levels, ungrounded price targets, or invented technical indicators causes an immediate verification failure.
3. If verified, the grounded synthesis is cached for 1 hour to prevent redundant LLM invocations and maintain cost predictability.

---

## 8. API Endpoints, Request Formats, and Response Schemas

### 8.1 Public Base URLs
- Primary Web Terminal: `https://trinetra.trade`
- Primary REST API: `https://api.trinetra.trade`

### 8.2 Endpoints Reference

#### `GET /health`
Returns system status, engine readiness, and version.
```json
{
  "status": "ok",
  "version": "0.1.0",
  "git_sha": "4a09435",
  "ai_configured": true
}
```

#### `GET /regime`
Returns the current broad market regime classification and internal health indicators.
```json
{
  "state": "risk_on",
  "index_above_200dma": true,
  "index_200dma_slope_up": true,
  "breadth_pct_above_50dma": 64.2,
  "india_vix": 13.1,
  "fii_dii_net_flow_cr": 1420.5
}
```

#### `GET /scan`
Returns the ranked candidates for the current trading session from The Eye.
```json
{
  "as_of": "2026-09-16",
  "universe_size": 2180,
  "scanned": 12,
  "picks": [
    {
      "rank": 1,
      "symbol": "NSE:RELIANCE",
      "sector": "Energy",
      "action": "BUY",
      "stage": 2,
      "rvol": 2.15,
      "pivot": 2980.0,
      "stop_loss": 2895.0,
      "freshness_pct": 1.8
    }
  ]
}
```

---

## 9. Legal & Execution Disclaimers

1. **Non-Execution Platform**: TRINETRA does not place orders, manage funds, or offer portfolio management services.
2. **Educational & Decision-Support Only**: All content, screening rankings, signals, and verdicts are algorithmic outputs generated for informational and research purposes. They do not constitute investment advice or solicitation under SEBI regulations.
3. **User Responsibility**: Capital markets involve substantial risk of loss. Users must perform independent due diligence and consult certified financial advisors before risking capital.