Buck: An AI-Powered Agent for Next-Day Stock Price Prediction

Repository: RyoK3N/Buck_V1
Version: 1.4.1
License: Apache 2.0
Language: Python (82.8%) · Jupyter Notebook (17.2%)

---

Overview

Buck is a stock analysis and prediction agent that combines classical technical analysis, news sentiment scoring, and GPT-4o-powered forecasting to generate next-day price predictions for individual stocks. Built with an async-first architecture and modular SOLID design, Buck is designed to be reliable, extensible, and easy to integrate into quantitative workflows — particularly for Indian stock markets (NSE/BSE), though it works with any ticker supported by Yahoo Finance.

The system takes a stock symbol and a historical date range as input, runs a battery of technical and sentiment analyses, and produces a structured forecast containing predicted Open, High, Low, and Close prices along with a confidence score and natural-language reasoning.

---

Problem Statement

Retail and quantitative investors face a common challenge: synthesizing disparate signals — price momentum, volume trends, candlestick patterns, and news sentiment — into a coherent short-term market view. Traditional approaches either require significant domain expertise to interpret raw indicators or rely on black-box ML models that offer little interpretability.

Buck addresses this by acting as an agent: it autonomously collects data, applies a suite of technical tools, and then uses a large language model to reason over the aggregated signals and produce an interpretable next-day forecast. The LLM reasoning step means predictions come with explanations, not just numbers.

---

How It Works

Buck's pipeline has four distinct stages:

1. Data Collection
Stock OHLCV data is fetched via yfinance (Yahoo Finance) for any user-specified symbol and date range. Optionally, news headlines for Indian equities can be pulled via an Indian News API, enabling sentiment enrichment.

2. Technical Analysis
Six technical indicators are computed over the historical window:

3. Sentiment Analysis
News headlines (when available) are scored using keyword-based sentiment analysis. The resulting sentiment signal is incorporated as a factor alongside the technical output.

4. AI-Powered Forecast (GPT-4o)
All analysis results are serialized and passed to OpenAI's GPT-4o model, which reasons over the indicators holistically to produce a structured next-day forecast: predicted OHLC prices, a confidence score between 0 and 1, and a natural-language rationale explaining the prediction.

---

Architecture

Buck follows SOLID software engineering principles with a clean layered architecture:

agent_scripts/
├── interfaces.py        # Abstract interfaces, protocols, BuckConfig dataclass
├── stock_agent.py       # Main orchestrator (StockAgent class)
├── data_providers.py    # Yahoo Finance + Indian News API integration
├── tools.py             # Individual technical indicator implementations
├── analyzers.py         # Coordinator: runs multiple tools and aggregates results
├── predictors.py        # GPT-4o prediction wrapper
├── config.py            # Environment variable management
└── cli.py               # Click-based command-line interface

buck_visualizer/         # Standalone interactive Plotly visualization scripts
tests/                   # pytest test suite

Key design decisions:

• Factory pattern (BuckFactory) for clean agent instantiation.
• Async/await throughout — all data fetching and analysis runs concurrently via asyncio.
• Built-in caching — results are stored to disk; repeated queries skip redundant API calls.
• Dependency injection — components are wired through interfaces, making the system easy to extend or swap (e.g., replacing the LLM predictor).

---

Key Features

• Next-day OHLC forecasting with confidence scores and human-readable reasoning.
• Batch analysis — analyze multiple tickers concurrently in a single call.
• Interactive visualizations — eight Plotly-based scripts (price_ma_plot.py, candlestick_volume_plot.py, macd_plot.py, bollinger_plot.py, rsi_plot.py, volatility_plot.py, returns_histogram.py, news_overlay_plot.py) for exploratory analysis.
• CLI — analyze stocks directly from the terminal without writing any Python.
• Configurable — model, temperature, token limits, news volume, and output directory are all tunable via environment variables or BuckConfig.

---

Quick Start

# Clone and install
git clone https://github.com/RyoK3N/Buck_V1
cd Buck_V1
pip install -r requirements.txt

# Set API keys
export OPENAI_API_KEY="your-openai-api-key"
export INDIAN_API_KEY="your-indian-api-key"  # optional, for news data

or create a .env file inside the Buck_V1 directory with all the required keys mentioned in the .env.example file

Python API:

import asyncio
from agent_scripts import create_agent

async def run():
    agent = create_agent(openai_api_key="your-key", model="gpt-4o")
    async with agent:
        results = await agent.analyze_and_predict(
            symbol="BHEL.NS",
            start_date="2024-01-01",
            end_date="2024-01-10",
            interval="1h"
        )
    forecast = results['forecast']
    print(f"Close: ₹{forecast['close']:.2f}  |  Confidence: {forecast['confidence']:.2f}")
    print(f"Reasoning: {forecast['reasoning']}")

asyncio.run(run())

CLI:

python -m agent_scripts.cli analyze BHEL.NS --start 2024-01-01 --end 2024-01-10
python -m agent_scripts.cli demo --symbol RELIANCE.NS

---

Output Schema

A successful analysis call returns a structured dictionary:

{
  "symbol": "BHEL.NS",
  "timestamp": "2024-01-15T10:30:00",
  "data_info": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-10",
    "interval": "1h",
    "data_points": 168,
    "news_available": true
  },
  "forecast": {
    "date": "2024-01-11",
    "open": 245.30,
    "high": 248.75,
    "low": 242.10,
    "close": 247.80,
    "confidence": 0.75,
    "reasoning": "RSI at 65 with MACD positive crossover..."
  },
  "metadata": {
    "model_used": "gpt-4o",
    "analysis_confidence": 0.82,
    "prediction_confidence": 0.75
  }
}

---

Limitations and Considerations

• Not financial advice. Buck is a research and educational tool. Predictions should not be used as the sole basis for investment decisions.
• LLM non-determinism. GPT-4o outputs may vary across runs at higher temperatures. The default temperature is set to 0.1 to maximize consistency.
• Sentiment scope. The news sentiment module currently uses keyword-based scoring rather than an embedding or fine-tuned sentiment model; results may be less nuanced for ambiguous headlines.
• Data availability. Prediction quality depends on the amount of historical data provided. Very short windows (fewer than ~30 data points) may limit indicator reliability.
• API costs. Each prediction call consumes OpenAI API tokens. Batch analysis of many tickers will incur proportional cost.

---

Roadmap

The repository is under active development. Potential directions for Buck V2 include:

• Fine-tuned or open-source LLM support (e.g., running locally via Ollama).
• Embedding-based semantic news sentiment using transformer models.
• Portfolio-level batch analysis with cross-ticker correlation.
• Backtesting harness to evaluate historical prediction accuracy.

---

Getting Involved

Bug reports, feature requests, and pull requests are welcome. See the contributing guidelines in the repository.

GitHub: https://github.com/RyoK3N/Buck_V1

---