StockAI Research Prototype

A small, submit-ready educational prototype that combines:

1. Cached financial-news sentiment for an immediate dashboard demo.
2. Live SEC EDGAR retrieval of a company's latest 10-Q using the SEC submissions API.
3. A transparent sentiment aggregation rule that produces a positive, negative, or mixed demo signal.

This project is for education and research. It is not investment advice and does not place trades.

Demo

What was fixed

The original pipeline built filing URLs ending in a generic index.html. Those requests frequently returned SEC navigation boilerplate instead of the primary 10-Q document. The corrected client:

• resolves the ticker to its SEC CIK;
• reads the latest 10-Q entry from data.sec.gov/submissions/CIK##########.json;
• uses the filing's exact accessionNumber and primaryDocument fields;
• validates that the downloaded document is large enough to resemble a real filing.

The old generated embeddings and GPT labels were deliberately excluded because they were derived mostly from bad source text. Keeping them would make the repository look complete while producing misleading results.

Demo architecture

flowchart LR
    A[Cached headline dataset] --> B[Sentiment aggregation]
    B --> D[Streamlit dashboard]
    C[SEC submissions API] --> E[Exact primary 10-Q document]
    E --> D

Loading

Run locally

python -m venv .venv

Windows:

.venv\Scripts\activate

macOS/Linux:

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Create your local environment file:

copy .env.example .env

On macOS/Linux use cp .env.example .env. Replace the placeholder in .env with your name and email because the SEC asks automated clients to identify themselves.

Start the dashboard:

streamlit run app.py

Or run the command-line version:

python main.py AAPL
python main.py AAPL --fetch-sec

Current scope and limitations

• The included headline data is a cached demonstration dataset, not a live news feed.
• The sentiment signal is an unweighted average of existing labels; it has not been backtested.
• Live SEC retrieval requires internet access.
• The prototype does not make financial predictions, execute trades, or claim investment performance.

Roadmap

Next practical improvements

1. Add a licensed/current news API and store article timestamps and publishers.
2. Add a reproducible sentiment model with confidence scores.
3. Extract specific 10-Q sections such as Risk Factors and MD&A.
4. Add ticker/date filters and persist downloaded filings under outputs/.
5. Create a backtest that prevents look-ahead bias and reports precision, drawdown, and benchmark performance.

Later research improvements

• Combine filing and news features only after their publication timestamps.
• Compare rule-based, classical ML, and language-model approaches.
• Add source citations for every generated explanation.
• Track data quality failures and API rate limits.

Repository notes

Do not commit .env, virtual environments, generated filing text, API keys, or the old corrupted FAISS/GPT artifacts. The included .gitignore already excludes them.