Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for BondRadar AI

BondRadar AI

BondRadar AI helps people discover and understand newly issued fixed-income bonds. It finds official SEC filings, extracts conventional bond terms with provenance, explains risks in plain English with OpenAI and supports transparent comparison.

Educational information only. BondRadar AI does not provide investment advice, execution, live quotes, credit ratings or suitability assessments.

Features

SEC EDGAR daily-index and issuer discovery
Conservative fixed-rate bond classification and extraction
Field-level source evidence and confidence
Review-first Django Admin workflow
Search, filters and sorting by yield, coupon, maturity, price, size or recency
Side-by-side comparison
OpenAI structured summaries and educational risk indicators
Novice knowledge centre covering terminology, cash flows, risks and trading mechanics
Responsive server-rendered interface

Quick start

git clone https://github.com/arshad2K8/bondradar-ai.git
cd bondradar-ai
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py seed_showcase
python manage.py runserver

Open http://127.0.0.1:8000/. seed_showcase creates two real, source-linked SEC records. Use python manage.py seed_demo only when you also want explicitly labelled fictional records.

On Windows PowerShell, activate the environment with:

.venv\Scripts\Activate.ps1

Configuration

Copy .env.example values into your environment or local .env. Django does not automatically load .env; export the variables in your shell or use your deployment platform’s environment settings.

Required for live SEC ingestion:

export SEC_USER_AGENT="BondRadar AI your-email@example.com"

Required for AI explanations:

export OPENAI_API_KEY="your-key"
export OPENAI_MODEL="gpt-5.6-luna"

Never commit API keys. .env and the local SQLite database are ignored by Git.

OpenAI enrichment

Generate source-constrained explanations for published real bonds:

python manage.py explain_bonds --limit 5

The Responses API returns a validated structure containing a summary, risk explanation, educational risk level and rationale. Model calls run offline through a command—not during page rendering—so the application remains responsive and usable without an API key.

OpenAI’s current model guidance recommends the Responses API and identifies Luna as the cost-sensitive member of the GPT-5.6 family. The model is configurable through OPENAI_MODEL.

Real-data ingestion

Follow known issuers:

python manage.py discover_sec 0000072971 0001652044

Discover a full SEC filing day and process a bounded batch:

python manage.py ingest_sec_daily --date 2026-07-20
python manage.py process_sec_inbox --limit 20

Process one curated accession:

python manage.py process_sec_inbox --accession 0000950103-25-004743

424B2 and 424B5 are candidate signals—not proof of a conventional bond. Extracted records enter review and retain official source links. The current deterministic extractor supports conventional USD fixed-rate note headings and rejects unsupported structured products.

Architecture

SEC indexes and filings
         ↓
  ingestion inbox
         ↓
classification + deterministic extraction
         ↓
canonical bonds + field evidence
         ↓
OpenAI structured explanation
         ↓
admin review → published catalogue

bonds/models.py — domain model, evidence and review states
bonds/services/sec.py — SEC access boundary
bonds/services/extraction.py — deterministic classifier/extractor
bonds/services/ai.py — OpenAI structured explanation boundary
bonds/services/catalogue.py — filtering and sorting
bonds/management/commands/ — repeatable ingestion and enrichment jobs
templates/ and static/ — server-rendered user interface

Admin and testing

python manage.py createsuperuser
python manage.py check
python manage.py test

Admin is available at http://127.0.0.1:8000/admin/.

Deployment

The repository includes a Procfile for a WSGI host. Configure:

DJANGO_SECRET_KEY
DJANGO_DEBUG=false
DJANGO_ALLOWED_HOSTS=your-domain.example
DJANGO_HSTS_SECONDS=31536000
DATABASE_URL for PostgreSQL
OPENAI_API_KEY if AI enrichment will run in that environment
SEC_USER_AGENT for SEC ingestion

Build and start commands:

python manage.py collectstatic --noinput
python manage.py migrate
gunicorn bondradar.wsgi:application

Data and safety

Public availability does not automatically grant redistribution rights.
SEC requests must use an honest contact User-Agent and respect fair-access guidance.
Commercial prices, ratings and identifiers may require separate licences.
A historical bond trade is not a current executable quote.
Generated explanations can be incomplete or incorrect and must remain linked to authoritative sources.
A BondRadar risk indicator is not an agency credit rating or prediction of default.

See PROJECT_STORY.md for the Devpost-ready project story.