MujtabaK/maqasid-equity-dashboard

Maqasid Equity Intelligence

Private-beta Streamlit dashboard for purpose-based (Maqasid) equity ranking beyond binary Shariah screening: four-methodology Shariah screening, filing-based deep research, Maqasid 100 index building, lead capture, user analytics, company search, and recent-events overlay.

Deploy On Hugging Face Spaces

1. 1.Create a new Hugging Face Space.
2. 2.Choose Docker as the SDK.
3. 3.Choose CPU Basic hardware.
4. 4.Upload all files in this folder to the Space (upload the folder contents, not the zip itself).
5. 5.Add secrets in Space settings:

SUPABASE_URL
SUPABASE_SERVICE_ROLE_KEY
RESEND_API_KEY
ADMIN_EMAIL
PRIVATE_ACCESS_TOKEN        (or PRIVATE_ACCESS_TOKENS for multiple links)
ADMIN_ACCESS_TOKEN
SEC_USER_AGENT              (must contain a real, reachable contact email)
FINNHUB_API_KEY
FMP_API_KEY
TWELVE_DATA_API_KEY
ALPHA_VANTAGE_API_KEY
NEWS_API_KEY
GNEWS_API_KEY
GEMINI_API_KEY
GEMINI_MODEL
LLM_MAQASID_MODE

Only PRIVATE_ACCESS_TOKEN or PRIVATE_ACCESS_TOKENS is required for the landing-page gate. Supabase and Resend are optional but strongly recommended: without Supabase, cache and lead writes fall back to the container's ephemeral .local_data/ directory, which is wiped on every Space rebuild (the Admin tab shows a warning when at-risk local rows exist). SnapTrade (SNAPTRADE_*) and PayPal (PAYPAL_*) secrets are only needed if those features are enabled.

File Map

app.py                     Main Streamlit dashboard, private-link lead gate, admin panel
config.py                  Environment variables and app constants
database.py                Supabase REST helper with local fallback + at-risk-data detection
emailer.py                 Resend lead-notification helper (HTML-escaped)
market_data.py             Finnhub, FMP and Alpha Vantage quote adapters (honest N/A fallback)
news_service.py            NewsAPI and GNews adapters
official_financials.py     SEC companyfacts fetcher for latest US 10-K/10-Q fields
universe_loader.py         FMP, Wikipedia, public CSV and embedded S&P 500 constituent loader
deep_research.py           SEC 10-K Item 1 extraction pipeline with Gemini evidence extractor
current_events.py          Recent 8-K controversy overlay
maqasid_scoring.py         Maqasid scoring engine (deep + lite paths, caps, baselines)
shariah_screening.py       Four-methodology Halal/Haram screening engine (word-boundary matching)
llm_evidence.py            Optional Gemini search-only explanation layer (cached, retried)
maqasid_index.py           Maqasid 100 index universe loader, ranking and snapshots
maqasid_index_analytics.py Index performance analytics (returns, volatility, drawdown, beta)
maqasid_index_pdf.py       Institutional PDF factsheet builder
portfolio_analysis.py      Portfolio screening view (SnapTrade integration)
performance_tracker.py     Maqasid Top 40 vs S&P 500 tracker (verified data only)
snaptrade_adapter.py       SnapTrade brokerage connection adapter
paypal_adapter.py          PayPal subscription adapter
bursa_adapter.py           Malaysia KLCI coverage via SC Malaysia official list
search_utils.py            Forgiving ticker/name search and misspelling matching
data_quality.py            Identity/data validation labels for dashboard rows
sample_data.py             Company row builder (screening + scoring assembly)
us_directory.py            NYSE/NASDAQ full-directory lookup
stress_test.py             Adversarial scoring diagnostics
test_smoke.py              Local smoke test for search, screening and scoring behaviour
test_deep_research.py      Mocked deep-research pipeline tests (incl. anti-gaming validation)
test_surveillance_validation.py  Surveillance false-positive guard tests
requirements.txt           Pinned Hugging Face Python dependencies
Dockerfile                 Streamlit container on port 7860
SETUP_GUIDE.md             Step-by-step deployment and API-key guide
DATA_POLICY.md             Data accuracy and validation policy
DEPLOYMENT_CHECKLIST.md    Pre-deploy checklist
SUPABASE_V3_0_MIGRATION.sql Supabase schema migration

Screening Flow

The app applies four indicative Shariah screening methodologies before Maqasid scoring:

• —Dow Jones
• —FTSE
• —Meezan Bank
• —Bank Negara Malaysia

If at least one methodology returns Halal, the company moves to Maqasid scoring. If all four return Haram, the app marks the company Not Halal and does not assign a Maqasid score. The business-activity screen uses whole-word keyword matching (covering alcohol, gambling, adult content, tobacco, pork, conventional finance and insurance, weapons, defence contracting, and intelligence/surveillance). Malaysian KLCI securities are governed by the official SC Malaysia Shariah-compliant list instead of computed ratios.

When GEMINI_API_KEY is configured, deep research extracts evidence from the latest SEC annual filing (10-K/20-F/40-F Item 1) with closed-vocabulary validation, and a search-only Gemini layer enriches the written explanation, Maqasid domains, risk flags, and evidence limitations. The LLM never decides Shariah eligibility, never sets numeric scores, and its output is validated and clamped before use. Extractions are durably cached per filing accession, so a company is only re-analysed when it files a new annual report or the prompt version changes.

For the dashboard universe, the app fetches the full current S&P 500 constituent list from Wikipedia, then FMP, then a public CSV, then a bundled offline CSV — an embedded constituent list guarantees the universe always loads.

For searched US companies, the app fetches the latest official SEC companyfacts data before screening: total assets, total debt, cash and equivalents, revenue, filing period end date, filing date, and source tag names. Market cap is taken from the market-data API when available. The quote-provider order is Finnhub, then FMP, then Alpha Vantage. If all providers fail, the price is shown as N/A — the app never displays fabricated quotes, and the Performance tab shows an honest empty state until an admin has snapshotted verified price history.

Private Link

If your Space URL is:

https://yourname-maqasid-equity-dashboard.hf.space

and your secret is:

PRIVATE_ACCESS_TOKEN=maqasid-beta-2026

share:

https://yourname-maqasid-equity-dashboard.hf.space/?access=maqasid-beta-2026

For multiple private links, use:

PRIVATE_ACCESS_TOKENS=MK-Maqasid297,MK-Maqasid786,MK-Maqasid457

Then share links such as:

https://yourname-maqasid-equity-dashboard.hf.space/?access=MK-Maqasid297
https://yourname-maqasid-equity-dashboard.hf.space/?access=MK-Maqasid786
https://yourname-maqasid-equity-dashboard.hf.space/?access=MK-Maqasid457

Visitors with the correct link see the lead form first. The dashboard unlocks only after they submit name, email, organization, role, and country. The admin panel is reached by appending &admin=YOUR_ADMIN_ACCESS_TOKEN to a valid access link.

Supabase Tables

Run SUPABASE_V3_0_MIGRATION.sql in the Supabase SQL Editor for the full schema. The minimum tables for the lead gate are:

create table if not exists leads (
  id bigint generated always as identity primary key,
  created_at timestamptz default now(),
  name text,
  email text,
  organization text,
  role text,
  country text,
  reason text,
  access_token text
);

create table if not exists events (
  id bigint generated always as identity primary key,
  created_at timestamptz default now(),
  email text,
  event_type text,
  page text,
  company_searched text,
  universe_filter text,
  session_id text,
  user_agent text
);

Notes

• —This is a private-beta validation tool, not a fatwa, not investment advice, and not an automated trading system.
• —Free market-data APIs have rate limits and licensing limits. Cache results and avoid redistributing data commercially until the data license is reviewed.
• —Public Hugging Face Spaces expose source code. Keep all API keys in Hugging Face Secrets, never in files.
• —The SEC requires a real contact email in the SEC_USER_AGENT string; placeholder addresses are throttled or blocked.