130 lines
8.1 KiB
Markdown
130 lines
8.1 KiB
Markdown
# HTMX Frontend Implementation Plan
|
|
|
|
This document outlines the architecture and step-by-step plan for building a new HTMX-based frontend for the TradingAgents project.
|
|
|
|
## 1. General Architecture
|
|
|
|
The frontend will be a single-page web application served by a lightweight Python backend (FastAPI). This backend will be responsible for serving the HTML, handling user requests to start the agent process, and providing real-time status updates. The frontend and backend code will be housed in a new top-level `webapp` directory to keep it separate from the core agent logic.
|
|
|
|
### Core Components:
|
|
|
|
* **FastAPI Backend:** A Python web server that will:
|
|
* Serve the main `index.html` file.
|
|
* Provide API endpoints for the frontend to interact with.
|
|
* Run the `TradingAgentsGraph` in a background thread.
|
|
* Maintain and serve the state of the execution process.
|
|
* **HTMX Frontend:** The user interface, which will:
|
|
* Display the configuration form and start button.
|
|
* Show a hierarchical view of the agent execution process.
|
|
* Poll the backend for status updates.
|
|
* Display the content of selected process steps (reports, messages, errors) on the right side of the screen.
|
|
* **Communication:** The frontend will communicate with the backend using a simple polling mechanism. The HTMX frontend will periodically request a status update from a `/status` endpoint. The backend will return a JSON object representing the current state of the execution tree. For displaying detailed content, the frontend will make specific requests to a `/content/{item_id}` endpoint.
|
|
|
|
## 2. Proposed Project Structure
|
|
|
|
To maintain separation of concerns, the new frontend code will live in a `webapp` directory.
|
|
|
|
```
|
|
C:\Users\kevin\repo\TradingAgents\
|
|
├───... (existing project files)
|
|
└───webapp/
|
|
├───main.py # FastAPI application
|
|
├───static/
|
|
│ └───styles.css # CSS for styling
|
|
└───templates/
|
|
├───index.html # Main HTML file
|
|
└───_partials/
|
|
├───left_panel.html # HTMX partial for the execution tree
|
|
└───right_panel.html # HTMX partial for the content view
|
|
```
|
|
|
|
## 3. Backend Implementation (FastAPI)
|
|
|
|
The `webapp/main.py` file will define the FastAPI application and its endpoints.
|
|
|
|
### API Endpoints:
|
|
|
|
* **`GET /`**: Serves the main `templates/index.html` page.
|
|
* **`POST /start`**:
|
|
* Accepts a JSON payload with the run configuration (`company_symbol`, etc.).
|
|
* Initializes the `TradingAgentsGraph`.
|
|
* Starts the `graph.propagate()` method in a background thread.
|
|
* Returns an initial response that replaces the config form with the main progress bar.
|
|
* **`GET /status`**:
|
|
* This is the main polling endpoint for HTMX.
|
|
* It will return an HTML partial (`_partials/left_panel.html`) rendered with the current state of the execution tree. The state will be stored in memory.
|
|
* **`GET /content/{item_id}`**:
|
|
* When a user clicks an item in the left panel, HTMX will call this endpoint.
|
|
* It will retrieve the specific content for that `item_id` from the in-memory state.
|
|
* It will return an HTML partial (`_partials/right_panel.html`) with the formatted content (e.g., a formatted report, a code block for a message, or a stack trace for an error).
|
|
|
|
### State Management & Integration:
|
|
|
|
To get real-time updates from the `TradingAgentsGraph`, we will need to instrument its execution. The plan is to modify the `TradingAgentsGraph` class slightly to accept a callback function.
|
|
|
|
1. **Modify `TradingAgentsGraph.__init__`**: Add an optional `on_step_end` callback parameter.
|
|
2. **Callback Execution**: Inside the graph's execution logic (after each agent or tool runs), this callback will be invoked with the details of the completed step (e.g., node name, output, status).
|
|
3. **Update Global State**: The callback function, defined in `webapp/main.py`, will update a global in-memory dictionary that represents the hierarchical execution tree. This tree will store the status, content, and relationships of all steps.
|
|
|
|
This approach avoids tight coupling and allows the web application to listen to the progress of the core agent logic.
|
|
|
|
## 4. Frontend Implementation (HTMX)
|
|
|
|
The frontend will be built using HTMX attributes directly in the HTML templates.
|
|
|
|
* **`templates/index.html`**:
|
|
* Contains the basic page structure: a top bar for the overall progress, a left panel for the execution tree, and a right panel for content.
|
|
* Includes the HTMX library.
|
|
* Contains the initial configuration form. The form will have an `hx-post="/start"` attribute to trigger the process.
|
|
|
|
* **Left Panel (`_partials/left_panel.html`)**:
|
|
* This partial will be the target of the status polling. The main container will have `hx-get="/status"` and `hx-trigger="load, every 2s"`.
|
|
* It will use a template loop (Jinja2) to render the hierarchical tree from the state object provided by the backend.
|
|
* Each item in the tree will be a clickable element with an `hx-get="/content/{item_id}"` attribute and an `hx-target="#right-panel"` attribute to load its content on the right side.
|
|
* The status of each item (pending, in-progress, completed, error) will be reflected using different CSS classes.
|
|
|
|
* **Right Panel (`_partials/right_panel.html`)**:
|
|
* A simple container (`<div id="right-panel">`) that gets its content replaced by HTMX when a user clicks an item on the left.
|
|
* Content will be pre-formatted by the backend (e.g., using Markdown-to-HTML conversion or syntax highlighting for code/errors).
|
|
|
|
* **Progress Bar**:
|
|
* The response from the initial `POST /start` call will replace the configuration form with a global progress bar.
|
|
* This progress bar's value will be updated as part of the `/status` polling response, by targeting its element ID with an `hx-swap-oob="true"` (Out of Band swap).
|
|
|
|
## 5. Detailed Implementation Steps
|
|
|
|
1. **Setup Environment**:
|
|
* Create the `webapp` directory and the file structure outlined above.
|
|
* Add `fastapi`, `uvicorn`, and `python-multipart` to the `requirements.txt` file and install them.
|
|
|
|
2. **Backend - Basic Server**:
|
|
* Create the initial FastAPI app in `webapp/main.py`.
|
|
* Implement the `GET /` endpoint to serve `templates/index.html`.
|
|
* Create a basic `index.html` with the two-panel layout.
|
|
|
|
3. **Backend - State & Integration**:
|
|
* Define the Python data classes for the execution state (e.g., `ProcessStep`, `RunState`).
|
|
* Modify `tradingagents/graph/trading_graph.py` to include the `on_step_end` callback mechanism.
|
|
* In `webapp/main.py`, implement the callback function that builds the hierarchical state tree in memory.
|
|
|
|
4. **Backend - Endpoints**:
|
|
* Implement the `/start` endpoint to receive configuration and launch the `propagate` method in a background thread, passing the callback function.
|
|
* Implement the `/status` endpoint to render and return the `_partials/left_panel.html` partial.
|
|
* Implement the `/content/{item_id}` endpoint to render and return the `_partials/right_panel.html` partial.
|
|
|
|
5. **Frontend - HTMX**:
|
|
* Develop the configuration form in `index.html` with `hx-post` to start the process.
|
|
* Create the `_partials/left_panel.html` template with the Jinja2 loop and the `hx-get` attributes for clicking on items.
|
|
* Add the polling mechanism to the main container in `index.html`.
|
|
* Style the different states (pending, completed, error) using CSS in `static/styles.css`.
|
|
|
|
6. **Error Handling**:
|
|
* When the callback receives an error, it will update the corresponding item's status to "error" and store the stack trace.
|
|
* The frontend will visually flag the item as an error.
|
|
* When clicked, the `/content/{item_id}` endpoint will return the formatted stack trace to be displayed in the right panel.
|
|
|
|
7. **Refinement**:
|
|
* Add a loading indicator for HTMX requests.
|
|
* Refine the CSS to ensure the application is visually appealing and user-friendly.
|
|
* Ensure the background process is managed correctly, especially in case of errors or server shutdown.
|