All Projects
Open Source · Market Intelligence

Parkhu AI

Parkhu AI is the data-collection layer of an institutional research operating system for Indian equities. GitHub Actions runs before market open and after close, gathering free-source intelligence from TradingView, NSE, and Yahoo Finance. Collectors write normalized CSV/JSON; derived steps build stock_analysis.csv with factor z-scores and regime context; the brief layer gates and sizes swing ideas with entry, stop, targets, hold period, and rupee position sizing. Every idea is tracked in trades/open.csv until its hold period ends - open positions are reviewed before anything new is proposed.

Problem

Institutional swing research for Indian equities needed a reliable pre-open data layer. Manual screeners, scattered NSE downloads, and ad hoc spreadsheets could not produce a gated, sized brief with audit trail every trading day - and one failed feed should not abort the entire run.

Before and After

Before

  • Manual TradingView / NSE checks each morning
  • No unified daily artifact or agent health report
  • Judgement and data collection mixed in one step
  • No tracked suggestion ledger across hold periods
  • LLM research required zip uploads or ad hoc exports

After

  • GitHub Actions premarket + post-close collection
  • Layered pipeline: collectors -> derived -> brief
  • One TradingView scan + targeted NSE/macro agents
  • swing_brief.md with gate funnel JSON audit trail
  • research_pack.md handoff under output/latest/

How Data Becomes a Swing Brief

GitHub Actions runs the collector before market open. Collectors gather free-source market data, derived steps build the indicator engine, and the brief layer gates and sizes swing ideas with a tracked suggestion ledger. Pick any block to see the flow.

Triggers

Orchestration

Collection

Processing

Brief

Delivery

What I Built

Multi-agent collection layer

  • TradingView one-call universe snapshot (~366 names) for price, valuation, technicals, and earnings.
  • NSE agents: smart money, options OI/PCR, derivatives, delivery, corp actions, and news.
  • Macro and indices from Yahoo for regime context (VIX, sectors, FX, global risk).
  • Agent contract returns ok | partial | error - runner continues on single-feed failure.

Derived indicator engine

  • relative_strength, event_risk, fno_momentum, and news_classify build on local CSVs only.
  • stock_analysis.csv: sub-scores, pivots, ATR levels, and factor z-scores vs universe.
  • market_summary.csv: one-row regime snapshot for the brief layer.
  • Serial OHLC database with daily append for ohlc_features.

Swing brief and suggestion ledger

  • Reviews trades/open.csv before proposing new ideas (MFE/MAE, days held, invalidation rules).
  • Hard gates, R:R checks, score bands, and portfolio caps from config/risk.py.
  • Outputs entry, stop, targets, hold period, expected profit %, and rupee position size.
  • funnel_detail.json and swing_brief.json document every gate survivor count.

Publish and dashboard delivery

  • Dated output/YYYY-MM-DD/ committed by data bot with manifest.json agent health.
  • research_pack.md/json under output/latest/ for LLM handoff without zip uploads.
  • GitHub Pages dashboard (site/) deployed separately from collect workflow.
  • pytest + ruff + vulture quality gate on code changes.

Engineering Decisions

  • TradingView single scan replaced four redundant Yahoo per-symbol agents - one HTTP pass for the universe.
  • Strict layer boundaries: collectors own I/O, derived reads CSVs, brief never calls external APIs.
  • Brief runs last and owns judgement; deterministic metrics live in stock_analysis.csv.
  • Data commits (output/, trades/) separated from code PRs - branch protection on main for code only.
  • Weekend runs stamp session_date and log warnings without pretending to be live session data.

By the Numbers

Universe snapshot

~366 symbols

Collector agents

13 registered

Derived steps

9 (brief last)

Daily output files

20+ CSV/JSON artifacts

Scheduled runs

Premarket + post-close IST

CI timeout budget

90 min (OHLC backfill)

Automated tests

80+ pytest cases

Reliability and Ops

  • One agent failure records error status and continues - partial days still publish.
  • COLUMNS schema contract with assert_unique_columns guards for wide tables.
  • publish_validate checks pack integrity before latest/ mirror.

Testing

  • pytest across brief, publish, OHLC, research backtest, and architecture boundary tests.
  • scripts/quality: ruff + vulture + jscpd on every code PR.
  • Collect workflow runs pytest before python run.py on scheduled jobs.

What I Did

  • 01Built a layered pipeline (collectors -> derived -> brief) with 13 I/O agents and 9 derived steps including stock_analysis and swing_brief.
  • 02Replaced four redundant Yahoo per-symbol agents with one cached TradingView universe scan (~366 names) plus NSE-only feeds.
  • 03Implemented swing brief gates, R:R checks, funnel audit JSON, and a suggestion ledger (trades/open.csv, trades/closed.csv).
  • 04Shipped research_pack.md under output/latest/ for LLM handoff and a GitHub Pages dashboard decoupled from the collect workflow.
  • 05Added pytest + ruff + vulture quality gate; agent failures record status=error without aborting the daily run.
Next: AI Job HunterGet in Touch