Skip to content

Commit 8637b5f

Browse files
Srikanth-ADSrikanth-AD
committed
Initial release: 14-layer AI investment thesis monitor
- 14 parallel data layers (prices, fundamentals, technicals, macro, news, SEC filings, GDELT geopolitics, Reddit, Google Trends, Wikipedia, hedge funds, insider trades, congress trades, ESG/sustainability) - Claude synthesis with thesis status (INTACT/SHAKEN/BROKEN) - Email alerts: urgent, daily digest, weekend prep - 74 unit tests, ruff lint clean - All free APIs except Claude (~$0.10-$5/month depending on model) - GitHub Actions CI + scheduling template for private repos
0 parents  commit 8637b5f

39 files changed

Lines changed: 4624 additions & 0 deletions

‎.env.example‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ── Required ──────────────────────────────────────────────────
2+
ANTHROPIC_API_KEY=your-api-key-here
3+
FINNHUB_API_KEY=your-finnhub-key-here
4+
5+
# ── Reddit (optional — leave blank to skip Reddit sentiment) ──
6+
REDDIT_CLIENT_ID=
7+
REDDIT_CLIENT_SECRET=
8+
REDDIT_USER_AGENT=thesis-engine/1.0
9+
10+
# ── Congress trades (optional — leave blank to skip Layer 13) ─
11+
QUIVER_API_KEY=
12+
13+
# ── Email alerts ──────────────────────────────────────────────
14+
# NOTIFY_EMAIL = your Gmail address (alerts go here)
15+
# EMAIL_PASSWORD = Gmail APP PASSWORD (16-char code from Google)
16+
# NOT your real Gmail password. Generate one at:
17+
# myaccount.google.com > Security > 2-Step Verification > App Passwords
18+
NOTIFY_EMAIL=your@email.com
19+
EMAIL_PASSWORD=your-gmail-app-password

‎.github/workflows/analyze.yml.example‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ======================================================================
2+
# thesis-engine -- Scheduled Analysis Workflow
3+
#
4+
# HOW TO USE:
5+
# 1. Copy this file to your PRIVATE repo (not the public fork)
6+
# 2. Rename to analyze.yml (remove .example)
7+
# 3. Add secrets in your repo: Settings > Secrets > Actions
8+
# 4. Enable GitHub Actions in your repo
9+
#
10+
# This runs the analyzer hourly during US market hours (Mon-Fri)
11+
# and once on Sunday evening for weekend prep.
12+
# ======================================================================
13+
14+
name: thesis-engine
15+
16+
on:
17+
schedule:
18+
# Hourly Mon-Fri 8am-5pm ET (12:00-21:00 UTC)
19+
- cron: "0 12-21 * * 1-5"
20+
# Sunday 6pm ET = 22:00 UTC Sunday
21+
- cron: "0 22 * * 0"
22+
workflow_dispatch: # Manual trigger from Actions tab
23+
24+
permissions:
25+
contents: write
26+
27+
jobs:
28+
analyze:
29+
runs-on: ubuntu-latest
30+
timeout-minutes: 10
31+
32+
steps:
33+
- uses: actions/checkout@v4
34+
35+
- uses: actions/setup-python@v5
36+
with:
37+
python-version: "3.11"
38+
39+
- name: Install dependencies
40+
run: pip install -r requirements.txt
41+
42+
- name: Run analyzer
43+
env:
44+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
45+
FINNHUB_API_KEY: ${{ secrets.FINNHUB_API_KEY }}
46+
REDDIT_CLIENT_ID: ${{ secrets.REDDIT_CLIENT_ID }}
47+
REDDIT_CLIENT_SECRET: ${{ secrets.REDDIT_CLIENT_SECRET }}
48+
REDDIT_USER_AGENT: thesis-engine/1.0
49+
QUIVER_API_KEY: ${{ secrets.QUIVER_API_KEY }}
50+
NOTIFY_EMAIL: ${{ secrets.NOTIFY_EMAIL }}
51+
EMAIL_PASSWORD: ${{ secrets.EMAIL_PASSWORD }}
52+
run: python analyzer.py --once
53+
54+
- name: Commit logs
55+
if: always()
56+
run: |
57+
git config user.name "github-actions[bot]"
58+
git config user.email "github-actions[bot]@users.noreply.github.com"
59+
git add logs/ context/ -f 2>/dev/null || true
60+
git diff --staged --quiet 2>/dev/null || (git commit -m "Update logs -- $(date -u '+%Y-%m-%d %H:%M UTC')" && git push) || true

‎.github/workflows/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- uses: actions/setup-python@v5
16+
with:
17+
python-version: "3.11"
18+
19+
- name: Install dependencies
20+
run: |
21+
pip install -r requirements.txt
22+
pip install pytest ruff
23+
24+
- name: Lint
25+
run: ruff check .
26+
27+
- name: Test
28+
run: pytest tests/ -v

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.env
2+
.venv/
3+
__pycache__/
4+
*.pyc
5+
.pytest_cache/
6+
.ruff_cache/
7+
logs/
8+
context/
9+
stocks.yaml

‎CODE_OF_CONDUCT.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to a positive environment:
15+
16+
* Using welcoming and inclusive language
17+
* Being respectful of differing viewpoints and experiences
18+
* Gracefully accepting constructive criticism
19+
* Focusing on what is best for the community
20+
* Showing empathy towards other community members
21+
22+
Examples of unacceptable behavior:
23+
24+
* The use of sexualized language or imagery and unwelcome sexual attention
25+
* Trolling, insulting or derogatory comments, and personal or political attacks
26+
* Public or private harassment
27+
* Publishing others' private information without explicit permission
28+
* Other conduct which could reasonably be considered inappropriate
29+
30+
## Enforcement
31+
32+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
33+
reported by opening an issue.
34+
35+
## Attribution
36+
37+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
38+
version 2.0.

‎CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributing to thesis-engine
2+
3+
Thanks for your interest in contributing! This project is a personal investment research tool, but improvements that help everyone are welcome.
4+
5+
## How to contribute
6+
7+
1. **Fork** the repository
8+
2. **Create a branch** for your change: `git checkout -b my-feature`
9+
3. **Make your changes** and add tests if applicable
10+
4. **Test locally**: `source .venv/bin/activate && pytest -v`
11+
5. **Lint**: `ruff check .`
12+
6. **Open a pull request** with a clear description of what changed and why
13+
14+
## Ideas for contributions
15+
16+
- **New data layers** -- additional free data sources (e.g., patent filings, job postings, app store rankings)
17+
- **Better sentiment analysis** -- improved keyword lists, NLP-based scoring
18+
- **New alert channels** -- Slack, Discord, Telegram, push notifications
19+
- **Dashboard** -- a simple web UI to view portfolio status without email
20+
- **Backtesting** -- compare thesis-engine alerts against historical price action
21+
- **International stocks** -- better support for non-US markets
22+
- **Options data** -- unusual options activity monitoring
23+
24+
## Guidelines
25+
26+
- **Free APIs only** -- thesis-engine should cost near-zero to run. No paid data providers unless there's a meaningful free tier.
27+
- **Graceful failure** -- every data layer must handle errors silently and return a useful fallback. One broken API should never crash the whole system.
28+
- **Test with `--test`** -- run `python analyzer.py --test` to verify end-to-end behavior before submitting.
29+
- **Pure function tests** -- unit tests should not require API keys. Use mocks for external calls, test pure logic functions directly.
30+
- **Keep it simple** -- this is a personal tool, not an enterprise platform. Prefer clarity over abstraction.
31+
32+
## Code style
33+
34+
- Python 3.10+
35+
- Formatted and linted with [Ruff](https://docs.astral.sh/ruff/)
36+
- Type hints are welcome but not required
37+
- Docstrings on public functions
38+
39+
## Reporting issues
40+
41+
Open an issue with:
42+
- What you expected to happen
43+
- What actually happened
44+
- Steps to reproduce (if applicable)
45+
- Relevant log output (redact any API keys or personal data)

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 thesis-engine contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)