⚡ KAPITL

Production-Grade Autonomous Multi-Account IPO Intelligence, MILP Capital Allocation & Pre-Market Execution Engine

A FastAPI + Next.js planning and tracking tool for Indian retail IPO investors (NSE/BSE).
Kapitl combines IPO feed data and grey-market signals with an LLM summary, a heuristic MILP capital allocator across family demat accounts, ASBA lock tracking, and scheduled Angel One SmartAPI listing-day sell staging. Prospectus (DRHP) parsing is not implemented, and broker order placement has not been verified against a live account.

---

📑 Executive Summary

Every year, millions of Indian retail investors participate in IPOs using manual intuition, missing out on optimal category quotas or getting disqualified by PAN duplication. Kapitl replaces spreadsheet guesswork with a rules-aware optimizer and scheduled execution tooling (heuristic, not a guarantee of allotment or profit):

┌─────────────────────────┐    ┌──────────────────────────┐    ┌─────────────────────────┐
│ Structured Data & Feeds │    │  MILP Capital Optimizer  │    │  SmartAPI Execution Bot │
│ Multi-Agent Due Diligence│───▶│  PuLP Family Allocator   │───▶│  09:00:00 AM Listing    │
│ 6-Factor Radar Score    │    │  Max Lot Lottery Odds    │    │  Pre-Market Limit Exit  │
└─────────────────────────┘    └──────────────────────────┘    └─────────────────────────┘

1. AI-assisted IPO scoring: an LLM (Groq openai/gpt-oss-120b by default; Anthropic Claude or Google Gemini can be selected in Settings, one provider at a time) summarises the IPO's feed metadata (price band, lot size, GMP, subscription, listed strengths and risks). Market-signal components (GMP, subscription) are computed deterministically. Anything the model cannot be given - restated financials, peer multiples, OFS split, litigation - is shown as not assessed; prospectus (DRHP/RHP) parsing is not implemented.
2. Heuristic capital allocation (PuLP MILP): given family balances across demat accounts, ranks bids across SEBI Retail (≤₹2L), sHNI (₹2L–₹10L) and bHNI (>₹10L) by a GMP × score weighting, with per-account budgets, one bid per PAN within a plan, a reservation of capital for high-score upcoming IPOs, and UPI-vs-net-banking tagging (UPI is capped at ₹5L per bid). The objective is a ranking heuristic, not expected profit: it has no allotment-probability model, so it makes no profit or allotment guarantee.
3. Listing-day sell staging (self-hosted scheduler or GitHub Actions cron): holdings credited in the demat are detected via Angel One SmartAPI (exact ISIN/symbol matching) and the sell limit price you stage is submitted around 09:00 IST on listing day, with a 10:05 reconciliation that books P&L only from real broker fills. Timing is best-effort, and the broker calls have not been verified against a live account.

---

🏛 System Architecture

Kapitl is built as an asynchronous platform connecting verified primary market feeds, linear programming engines, LLM pipelines, and direct broker APIs:

graph TD
    subgraph Data Ingestion & Live Feeds
        A1[ipoalerts.in API] -->|Primary Market Schedule| B(Identity Resolver & Ingestion Service)
        A2[Groww Financial Endpoints] -->|Pricing & Lot Rules| B
        A3[ipowatch.in Scraper] -->|Live GMP Signals| B
    end

    subgraph Quantitative & Multi-Agent AI Pipeline
        B --> C[(PostgreSQL 15 / Async SQLAlchemy)]
        C --> D[6-Factor Financial Multiplier Engine]
        D --> E1[Equity Research Agent: Financials & Valuations]
        D --> E2[Market Intelligence Agent: Promoter & Sentiment]
        E1 & E2 -->|Composite 0-100 Score & Radar Vector| C
    end

    subgraph Operations Research & Capital Optimizer
        F[Multi-Account Family Pool] -->|SmartAPI RMS Balance Sync| C
        C --> H[PuLP MILP Solver: CBC Engine]
        H -->|Deterministic Category & Lot Matrix| I[ASBA Capital & Lock Scheduler]
    end

    subgraph Broker Execution & Client Terminal
        I -->|Depository Polling Worker| J[09:00:00 AM IST Pre-Market Exit Engine]
        J -->|Automated SmartAPI Sell Orders| K[NSE / BSE Matching Engine]
        C --> L[Next.js 14 App Router Terminal]
        M[FastAPI Async WebSocket] -->|Live Market Ticker & Alerts| L
    end

---

📐 Algorithmic Breakdown: Operations Research (MILP)

The Problem

SEBI (Securities and Exchange Board of India) enforces strict IPO bidding rules:

• Retail Quota: Bids $\le$ ₹2,00,000. Allotment is a pure lottery (1 lot per winner, regardless of lots bid).
• Small HNI (sHNI): Bids > ₹2,00,000 and $\le$ ₹10,00,000. Allotment is proportionate / lottery with minimum 1 sHNI lot.
• Big HNI (bHNI): Bids > ₹10,00,000. Allotment proportional to oversubscription.
• PAN Penalty: Bidding twice under the same PAN in the same category invalidates all applications.

This is the beginning of the README. Read the rest at the original. Read the full README ↗