{"id":"27954310-2471-4926-9c09-f1cc5fd8ea5f","slug":"vanillaforge","kind":"skill","name":"VanillaForge","summary":"","owner":"SHard777","repoUrl":"https://github.com/SHard777/VanillaForge","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-05T22:34:10.000Z","addedAt":"2026-10-21T21:28:56.884Z","logoUrl":"https://avatars.githubusercontent.com/u/155732805?u=b8197acc4869852c24a10bafc5c9c8399662ec47&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T22:33:03.167Z","sample":false,"url":"https://conduits.dev/tools/vanillaforge","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# VanillaForge Agent\n\n![VanillaForge Cat Trader](assets/funny_banker_cat3.jpg)\n\nVanillaForge is an AI-powered financial analysis and derivatives analytics agent built on Google's **Agent Development Kit (ADK) 2.0**, powered by **Gemini**, and developed with **Antigravity IDE** following modern **agentic engineering best practices**.\n\nIt offers deep expertise in financial derivatives by ingesting and referencing financial textbooks and academic research papers. It can price a wide range of European option strategies, retrieve live and historical market data, access company financial information, generate interactive charts, perform real-time sentiment analysis, and suggest option strategies based on positive, neutral, or negative market expectations. Additionally, VanillaForge features a persistent journal that records theoretical trades and tracks how market sentiment evolves over time for selected companies.\n\n**Key Capabilities:**\n* Deep expertise in derivatives\n* Pricing European option strategies\n* Delivering company financial and business insights\n* Retrieving live and historical market data\n* Generating interactive market charts\n* Computing option Greeks and risk metrics\n* Suggesting strategies based on positive, neutral, or negative market expectations\n* Performing real-time market sentiment analysis\n* Maintaining a persistent journal of theoretical trades and sentiment observations\n\n\nOriginally a generic options derivative conversational assistant, it has been heavily customized following the advanced \"Agent Skills\" from Google ADK architecture, specifically leveraging **Progressive Disclosure** and **Shift Intelligence Left** to minimize token usage, resolve issues before execution, and remain highly efficient and secure. \nIn addition, it utilizes a dedicated local MCP server as a persistent long-term memory to log derivative trade strategies on demand, and track sentiment analysis over time for any equity of your choosing.\n\n\n**⚠️ Disclaimer: This recommendation is for educational purposes only and should not be considered financial advice.**\n\nThis project forms part of the capstone submission for the Kaggle/Google Intensive Vibe Coding Capstone Project. I am deeply grateful to Google and the outstanding instructors for providing such a valuable program at the forefront of this disruptive technological revolution.\n\nA special thank you to my wonderful wife for her unwavering patience, support, and encouragement throughout this project. Your understanding, belief in me, and constant support during the many hours devoted to this work made all the difference.\n\nThe code and opinions expressed here are my own and do not represent Google or Kaggle.\n\n\n\n## Tech Stack\n\n| Category | Technology |\n|:---|:---|\n| **Agent Framework** | Google ADK 2.0 |\n| **LLM** | Google Gemini  |\n| **MCP Server** | FastMCP + SQLite |\n| **RAG / Vector DB** | ChromaDB + PyPDF |\n| **Market Data** | yfinance + Pandas + PyArrow |\n| **Visualization** | Seaborn + Matplotlib |\n| **Backend API** | FastAPI + Uvicorn + WebSockets |\n| **Frontend** | React + Vite + Tailwind CSS |\n| **Package Manager** | uv |\n| **Testing** | Pytest + pytest-asyncio |\n| **Linting** | Ruff + Mypy + Codespell |\n\n\n## Architecture Overview\n\nThe agent is designed as a single, deterministic orchestration engine (`VanillaForge_agent`) locked at `temperature=0.1`. Instead of a complex, brittle routing graph, the agent dynamically discovers and loads independent tools from the `skills/` directory at runtime only when needed, in order to save token usage and avoid context memory rot (hallucination).\n\n```text\n                       [START]\n                          │\n                 [VanillaForge_agent]\n                /         │          \\\n      (Dynamic Skills)    │     (MCP Integration)\n            /             │             \\\n           ▼              ▼              ▼\n   [pricing_skill]  [data_skill] ...  [memory_mcp_server]\n           │              │              │\n           ▼              ▼              │ (Direct ADK integration)\n[skill_loader.py (SkillToolset)]         │\n[Injects __agent_instructions__]         │\n           │              │              │\n            \\             │             /\n             ▼            ▼            ▼\n                 [VanillaForge_agent]\n                          │\n                    (User Resumes)\n```\n\n### The `SkillToolset` Loader (`app/skill_loader.py`)\nAt the core of the architecture is the automated `skill_loader.py`. \nWhen the agent starts, it scans the `skills/` directory and parses the lightweight YAML metadata from each `SKILL.md` file. It then automatically intercepts tool execution to inject the heavy Markdown instructions (`__agent_instructions__`) into the payload *only when the skill is actually used*. This prevents \"Context Rot\" and keeps the agent fast and cheap.\n\n## Available Skills\n\nThe `VanillaForge_agent` currently possesses 5 core capabilities:\n\n1. **`documentation_skill`**: **Soaks up educational derivatives textbooks to teach you financial theory.** It performs RAG over a local ChromaDB to answer complex educational options theory questions without hallucinating. Includes also a built-in ingestion tool (`scripts/ingest_pdfs.py`) to easily drop new PDFs into `Documents_options/` and instantly expand the agent's knowledge base.\n2. **`company_information_skill`**: **Provides basic company profile and financials.** It scrapes and retrieves specific fundamental metadata about a publicly traded company.\n3. **`pricing_skill`**: **Calculates the fair price and risk metrics of any strategy based on European vanilla options.** It acts as a Black-Scholes-Merton (BSM) calculator for European options. If the user omits inputs, an internal sub-agent seamlessly fetches the live Spot Price, Implied Volatility, and Dividend Yield from Google Search before computing the option premium and Greeks.\n4. **`data_skill`**: **Downloads historical market data and draws pricing charts.** It uses `yfinance` to download market data, persists massive datasets locally as high-performance `.parquet` and `.csv` files, and generates `seaborn` visualizations.\n5. **`news_sentiment_skill`**: **Reads the news to tell you if the market is bullish or bearish on a stock.** It retrieves the top 10 most recent news articles for an equity and performs a rigid semantic sentiment analysis on each, returning a structured 0-100 score and thematic breakdown.\n\n## MCP Servers\n\nModel Context Protocol (MCP) servers run independently and provide the agent with standardized external memory and capabilities:\n\n1. **`memory_trade_sentiment`**: **Acts as the agent's persistent long-term memory for trade strategies and equity market sentiment.** It runs a local SQLite database (`vanillaforge_memory.db`) via the FastMCP protocol, allowing the agent to invisibly log theoretical derivatives trades (including implied volatility) and track historical market sentiment for equities you have analyzed and chosen to log.\n    * *Example:* In a week's time, you can ask: *\"How did that CVX option I priced last Tuesday perform?\"*\n    * *Example:* Over a few weeks, the agent could query the MCP and tell you: *\"CVX sentiment was extremely bullish (85) two weeks ago, but the local database shows it has been steadily declining to 45 today. The trend is reversing.\"* This effectively turns a stateless agent into a persistent, analytical memory bank.\n\n\n---\n\n## Directory Structure\n\n*   **`app/agent.py`**: The central orchestrator Agent configuration and persona.\n*   **`app/skill_loader.py`**: The automated Progressive Disclosure framework loader.\n*   **`skills/`**: Contains the decoupled skill logic. Every skill has its own `SKILL.md` (metadata and instructions) and a `scripts/` folder containing the Python tools.\n*   **`mcp_servers/`**: Contains the local Model Context Protocol (MCP) servers, such as the persistent SQLite memory server for derivatives trades and equity sentiment analysis journaling.\n*   **`scripts/ingest_pdfs.py`**: Pipeline script to extract, chunk, and embed new PDFs into the local ChromaDB database.\n*   **`Documents_options/`**: Drop folder for new PDF textbooks and references.\n*   **`evals/eval_cases.json`**: The test suite used for Evaluation-Driven Development (EDD) of all skills.\n*   **`tests/`**: Pytest assertions covering the agent flow and skill capabilities.\n\n---\n\n## Standalone Dashboard Architecture\n\nThe VanillaForge Dashboard provides an **Agent-to-User Interface (A2UI)** financial terminal while **keeping the original ADK Web fully functional**. It converts a stateless CLI agent into a fully reactive, 6-panel financial terminal using FastAPI and React.\n\n### 1. Dashboard Layout & Component Architecture\nThe frontend uses a CSS Grid layout mimicking modern financial terminals (e.g., Bloomberg).\n\n```text\n+-------------------------+-----------------------------------------+\n| [Top-Left]              | [Top-Right]                             |\n| Main Chat               | Historical Market Data Chart            |\n| (Websocket to Agent)    | (ECharts; Time-Series OHLC plotting)    |\n+-------------------------+-----------------------------------------+\n| [Middle-Left]           | [Middle-Right]                          |\n| Option Pricer           | Company Information                     |\n| (Inputs, Greeks, &      | (Explicit financial metrics,            |\n| BSM theoretical price)  | valuation, business segments)           |\n+-------------------------+-----------------------------------------+\n| [Bottom-Left]           | [Bottom-Right]                          |\n| News Sentiment          | MCP Trade & Sentiment Journal           |\n| (Recent Headlines/Score)| (Dropdown: Trade / Sentiment tables)    |\n+-------------------------+-----------------------------------------+\n```\n\n### 2. The Internal \"A2UI\" Webhook Protocol\nTo achieve Progressive Disclosure without polluting the chat interface with raw JSON, the architecture relies on **Tool-emitted Internal Webhooks**. Instead of forcing the LLM to output UI commands, the underlying Python scripts (`fetch_profile`, `news_fetcher`, etc.) intercept the data internally. They fire a behind-the-scenes HTTP request directly to the FastAPI backend's internal endpoint (`/api/internal/a2ui`) to sync the React dashboard, and then strip the JSON away to return *only* beautiful, clean text to the Main Agent. This ensures a pristine chat experience in ADK Web/CLI while keeping the dashboard reactive in real-time.\n\n| Skill Name | Dashboard Panel | A2UI Data Flow |\n| :--- | :--- | :--- |\n| `VanillaForge_agent` | **Top-Left (Chat)** | Streams clean text directly to the chat log (No JSON). |\n| `data_skill` | **Top-Right (Chart)** | Tool POSTs webhook. Frontend fetches JSON from `/api/data/chart` and plots interactive graph. |\n| `pricing_skill` | **Middle-Left (Pricer)** | Tool POSTs BSM outputs via webhook. Frontend renders Greeks gauges/metrics. |\n| `company_information_skill`| **Middle-Right (Info)** | Tool POSTs company metadata via webhook. Frontend updates profile cards. |\n| `news_sentiment_skill` | **Bottom-Left (News)** | Tool POSTs sentiment score and headlines via webhook. Frontend updates sentiment dial. |\n| `memory_trade_sentiment` | **Bottom-Right (Journal)**| Frontend polls `/api/mcp/journal` directly to populate DataTables via MCP stdio. |\n\n### 3. Data Flow Diagram\nThe backend (FastAPI) acts as a lightweight wrapper that orchestrates the streaming LLM response and handles internal UI event webhooks triggered by the tools.\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant F as Frontend (React)\n    participant B as Backend (FastAPI)\n    participant A as ADK Agent\n    participant S as Skills (Python Tools)\n\n    U->>F: \"Plot AAPL chart\"\n    F->>B: WebSocket /chat: \"Plot AAPL\"\n    B->>A: invoke(VanillaForge_agent)\n    A->>S: execute(data_skill)\n    S->>B: POST /api/internal/a2ui {ui_action: UPDATE_CHART}\n    B-->>F: WebSocket State Update (Updates Gauges)\n    S-->>A: Clean Markdown Text\n    A-->>B: Streamed Text Response (No JSON)\n    B-->>F: Streamed Response\n    F->>U: Displays clean text in chat\n    F->>B: GET /api/data/chart?ticker=AAPL\n    B->>S: Read Parquet file\n    S-->>B: Dataframe\n    B-->>F: JSON Time-Series Data\n    F->>U: Renders interactive Top-Right Chart\n```\n\n---\n\n## Getting Started\n\n### 1. Prerequisites\nEnsure you have `uv` installed. If not, follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).\n\nInstall `google-agents-cli` (**Windows / macOS / Linux**):\n```bash\nuv tool install google-agents-cli\n```\n\n### 2. Configure Local Authentication\nDuplicate the `.env_example` template:\n\n**Windows:**\n```bash\ncopy .env_example .env\n```\n**macOS/Linux:**\n```bash\ncp .env_example .env\n```\n\nSet your `GEMINI_API_KEY` in the `.env` file to authenticate with Google AI Studio.\n\n### 3. Install Dependencies\nRun the install command to sync package dependencies (**Windows / macOS / Linux**):\n```bash\nagents-cli install\n```\n\n### 4. Build the Local Database\nBefore running the agent, you need to ingest the options PDFs into the local Chroma vector database. Run the following command (**Windows / macOS / Linux**):\n```bash\nuv run python scripts/ingest_pdfs.py\n```\n\n---\n\n## Running the ADK Agent\n\n### Command Line Smoke Tests\nRun a quick educational test query (**Windows / macOS / Linux**):\n```bash\nagents-cli run \"What is a call option?\"\n```\n\nTest the advanced CVX pricing calculation (with automated dividend yield retrieval) (**Windows / macOS / Linux**):\n```bash\nagents-cli run \"Price a 1-year call option on CVX with a strike of 150.\"\n```\n\n### Interactive ADK Web Playground\nLaunch the local web-based playground to chat with the agent. \n\n![ADK_Web](assets/ADK_Pricing_skill_example.png)\n\n**Windows:**\n```bash\nuv run adk web .\n```\n\n**macOS/Linux:**\n```bash\nagents-cli playground\n```\n\nOnce started, the terminal will print the exact local URL. Typically, you can open your browser and navigate to:\n[http://127.0.0.1:8080/dev-ui/?app=app](http://127.0.0.1:8080/dev-ui/?app=app)\n*(Note: If port 8080 is already in use on your machine, the terminal output will provide the alternative port number).*\n\n### Standalone Local Web Dashboard\n\n![Dashboard local web](assets/Dashboard2.png)\n\n\nTo launch the custom interactive VanillaForge local web dashboard, you will need to start both the backend API and the frontend UI in two separate terminals. These commands are the same for all platforms (**Windows / macOS / Linux**).\n\n**Terminal 1 (Backend API):**\n```bash\nuv run uvicorn dashboard_backend.main:app --host 0.0.0.0 --port 8000 --reload\n```\n\n**Terminal 2 (Frontend UI):**\n```bash\ncd dashboard_frontend\nnpm install\nnpm run dev\n```\n\nThen open your browser and navigate to the provided local URL. For example **[http://localhost:5173](http://localhost:5173)** to access the dashboard.\n\n---\n\n## Current Limitations\n\n- Currently supports European option pricing only.\n- Limited support for advanced derivatives and structured products.\n- Limited charting and visualization capabilities.\n- Company information is currently retrieved primarily through Google Search.\n- Sentiment analysis is performed on demand rather than continuously.\n- No portfolio-level aggregation of trades and Greeks.\n- Prototype deployment intended for demonstration purposes.\n\n\n---\n\n## Next Steps\n\nIf I had more time, I would extend VanillaForge with the following capabilities and explore its evolution into a commercial-grade platform:\n\n- Support for more advanced derivatives and structured products beyond European options.\n- Visualization of payoff diagrams for complex option strategies directly within the dashboard.\n- Automated daily sentiment tracking for a configurable watchlist of equities.\n- Enhanced company intelligence, including richer financial metrics and fundamentals.\n- A comprehensive trading book with portfolio-level Greeks and risk analytics.\n- Leveraging historical trade and sentiment journals to generate personalized trading insights, analytics, and strategy suggestions.\n- More advanced charting and analytics capabilities.\n- Improved dashboard user experience and interface design.\n- Cloud deployment and scaling on Google Cloud Platform.\n\n---\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.\n"}