MarketSenseAgent is a Python-based market intelligence workflow for market data analysis, risk awareness, report generation, and Telegram delivery.
This project is designed as a decision-support and learning tool. It is not a trading bot and does not provide financial advice.
MarketSenseAgent helps collect market data, validate stock pools, analyse trend signals, generate market briefs, and send summaries through Telegram.
The project also includes an optional OpenAI enhancement layer for AI-generated market commentary. If OpenAI API quota or billing is unavailable, the system can safely skip the AI commentary step and keep the original workflow running.
- Stock pool validation
- Market data fetching
- Trend analysis
- Position and risk analysis
- Market news collection
- Daily and session brief generation
- Telegram report delivery
- Optional OpenAI AI market commentary
- Safe fallback when OpenAI API quota is unavailable
- GitHub portfolio-ready project structure
- Basic secret safety check before public release
- Validate stock pool
- Fetch market data
- Run trend analysis
- Run position analysis
- Collect market news
- Generate market brief
- Optionally generate OpenAI AI commentary
- Send report through Telegram
Create a local .env file based on .env.example.
Required local configuration:
OPENAI_API_KEY=your_openai_api_key_here OPENAI_MODEL=gpt-5.5
Optional Telegram configuration should be stored locally and never committed to GitHub.
Important: Do not upload .env, Telegram tokens, OpenAI API keys, private datasets, personal investment records, or customer data to GitHub.
Run the main workflow:
python run_all.py
Run the OpenAI safe runner test:
python tests/test_openai_safe_runner.py
Run the GitHub safety check:
python tests/check_github_safety.py
Generate project snapshot:
python tests/generate_project_snapshot.py
The OpenAI integration is currently optional.
The project includes:
- modules/openai_market_commentator.py
- modules/openai_market_commentary_safe_runner.py
If OpenAI API quota is unavailable, the safe runner generates a skipped report instead of crashing the workflow.
This design allows the base MarketSenseAgent workflow to continue running even without active OpenAI API billing.
Telegram is used as the report delivery channel.
The public GitHub version should only include example Telegram configuration files. Real bot tokens and chat IDs must stay local and must not be uploaded.
This project demonstrates:
- Python automation
- market workflow thinking
- finance and business domain awareness
- modular project structure
- Telegram automation
- OpenAI API integration structure
- safe fallback design
- GitHub release safety awareness
The public portfolio version should include documentation, architecture, sample outputs, screenshots, and selected non-sensitive code.
The private core version should keep API keys, private strategies, personal data, commercial logic, and sensitive prompts private.
V1.0:
- Local market analysis workflow
- Telegram delivery
- OpenAI integration structure
- Safe fallback runner
V1.1:
- Improve GitHub documentation
- Add screenshots
- Add sanitized sample outputs
- Prepare public showcase repository
V1.2:
- Re-enable OpenAI API with a small budget
- Add AI commentary into Telegram reports
- Improve prompt design and structured outputs
V1.3:
- Add LangChain or LangGraph workflow layer
- Convert modules into tools
- Add market memory and watchlist context
V1.4:
- Add dashboard
- Add cloud deployment
- Add user settings
- Explore commercial delivery model
This project is for learning, data analysis, workflow automation, and risk awareness only. It does not provide financial advice, does not guarantee returns, and should not be used as a direct buy or sell signal.