fix it

Author: DidierRLopes

99-advanced-examples/70-portfolio-commentary/README.md

@@ -1,106 +1,147 @@
-# Portfolio Commentary Copilot
-
-This is a FastAPI-based copilot service that provides portfolio commentary and analysis capabilities. The service utilizes DeepSeek for reasoning and Perplexity for web search based on user requests. It is designed to work with OpenBB Workspace and can be deployed using Docker or run locally.
-
-## Architecture
-
-```sh
-┌─────────────────────┐                ┌─────────────────────┐
-│                     │                │                     │
-│   OpenBB Workspace  │ ───────────>   │   Portfolio         │
-│      (Frontend)     │     HTTP       │   Commentary        │
-│                     │    Request     │   Copilot           │
-│                     │                │   (Backend)         │
-│                     │   <───────────-│                     │
-│                     │      SSE       │                     │
-└─────────────────────┘                └─────────────────────┘
-```
-
-The architecture consists of two main components:
-
-1. **OpenBB Workspace (Frontend)**: The user interface where queries are entered
-2. **Portfolio Commentary Copilot (Backend)**: A FastAPI service that processes queries and returns analysis
+# Portfolio Commentary Agent
 
-## Project Structure
-
-```
-portfolio-commentary/
-├── portfolio_commentary/
-│   ├── main.py          # Main FastAPI application
-│   ├── functions.py     # Core functionality
-│   ├── prompts.py       # LLM prompts
-│   └── agents.json      # Copilot configuration
-├── common/              # Shared utilities
-├── pyproject.toml       # Project dependencies
-├── Dockerfile           # Docker configuration
-└── fly.toml             # Fly.io deployment config
-```
+A sophisticated AI-powered portfolio analysis agent built for OpenBB Workspace. This agent provides intelligent commentary and insights on portfolio performance, allocation, and risk metrics by analyzing widget data from your dashboard.
 
 ## Getting Started
 
-Here's how to get your copilot up and running:
-
 ### Prerequisites
 
 - Python 3.10 or higher
-- Poetry for dependency management
+- Poetry for dependency management (or pip)
 - Docker (optional, for containerized deployment)
-- Your OpenRouter API key
+- OpenRouter API key for AI model access
 
-### Installation and Running
+### Environment Setup
 
-1. Clone this repository to your local machine.
+1. **Clone and navigate to the project:**
+```bash
+cd 99-advanced-examples/70-portfolio-commentary
+```
 
-2. Create and activate a virtual environment:
-```sh
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+2. **Create environment file:**
+Create a `.env` file with the following variables:
+```env
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+OPENROUTER_MODEL=deepseek/deepseek-chat-v3-0324
+OPENROUTER_MODEL_PERPLEXITY=perplexity/sonar
 ```
 
-3. Install dependencies using Poetry:
-```sh
+### Local Development
+
+**Option 1: Using Poetry**
+```bash
+# Install dependencies
 poetry install --no-root
-```
 
-4. Set up environment variables:
-Create a `.env` file in the root directory with the following content:
-```
-OPENROUTER_API_KEY=<your-api-key>
+# Run the server
+poetry run uvicorn portfolio_commentary.main:app --reload --port 7777
 ```
 
-5. Run the development server:
-```sh
-cd 70-portfolio-commentary
-poetry run uvicorn portfolio_commentary.main:app --reload --port 7777
+**Option 2: Using pip**
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install fastapi uvicorn python-dotenv httpx sse-starlette openbb-ai
+
+# Run the server
+uvicorn portfolio_commentary.main:app --reload --port 7777
 ```
 
 ### Docker Deployment
 
-1. Build the Docker image:
-```sh
+```bash
+# Build the image
 docker build -t portfolio-commentary .
-```
 
-2. Run the container:
-```sh
+# Run the container
 docker run -p 7777:7777 --env-file .env portfolio-commentary
 ```
 
-### Fly.io Deployment
+## Configuration
+
+### OpenBB Workspace Integration
+
+The agent automatically registers with OpenBB Workspace through the `/agents.json` endpoint. It supports:
+
+- **Streaming responses** for real-time analysis
+- **Widget dashboard selection** for data source integration
+- **Perplexity search feature** as an optional enhancement
+
+### Feature Toggles
+
+**Perplexity Search** (`perplexity-search`):
+- Enables real-time web search capabilities
+- Provides current market context and news
+- Uses Perplexity model via OpenRouter
+- Default: Disabled
+
+## Usage
+
+### 1. **Add Portfolio Widgets**
+- Add relevant widgets to your OpenBB Workspace dashboard
+- Common widgets: Performance charts, Holdings tables, Allocation breakdowns, Risk metrics
+
+### 2. **Select Widget Data**
+- Use the widget selection feature in OpenBB Workspace
+- The agent will automatically detect and process the selected widget data
 
-The project includes a `fly.toml` configuration for deployment to Fly.io. To deploy:
+### 3. **Enable Features (Optional)**
+- Toggle "Perplexity for Search" for enhanced market context
+- This adds real-time research capabilities to your analysis
 
-0. Go into agents.json and change `"query": "https://portfolio-commentary.fly.dev/v1/query"` to `"query": "https://<YOUR-FLY-IO-APP-NAME>.fly.dev/v1/query"`. This will make sure that OpenBB workspace utilizes this endpoint.
-1. Install the Fly CLI
-2. Run `fly launch` to create a new app
-3. Set your environment variables using `fly secrets set`
-4. Deploy with `fly deploy`
+### 4. **Request Analysis**
+- Ask questions about your portfolio
+- Examples:
+  - "Provide a commentary on my portfolio performance"
+  - "What are the key risks in my current allocation?"
+  - "How has my portfolio performed relative to benchmarks?"
 
-### Accessing the Documentation
+## API Endpoints
+
+- **GET `/agents.json`**: Agent configuration for OpenBB Workspace
+- **POST `/v1/query`**: Main query endpoint for portfolio analysis
+- **GET `/docs`**: Interactive API documentation (FastAPI Swagger UI)
+
+## Technical Details
+
+### AI Models
+- **Default**: DeepSeek Chat v3 (cost-effective, high-quality analysis)
+- **Enhanced**: Perplexity Sonar (when search feature is enabled)
+- **Streaming**: Real-time response delivery via Server-Sent Events
+
+### Dependencies
+- **FastAPI**: Web framework and API server
+- **OpenBB AI**: Widget data integration and processing
+- **OpenRouter**: AI model access and management
+- **httpx**: HTTP client for external API calls
+
+### Dynamic Prompt System
+The agent uses intelligent prompt generation that adapts based on:
+- Available widget data and context
+- Enabled features (Perplexity search)
+- Analysis requirements and user requests
+
+## Development
+
+### Local Testing
+```bash
+# Access API documentation
+http://localhost:7777/docs
+
+# Test agent configuration
+curl http://localhost:7777/agents.json
+```
 
-Once the API server is running, you can view the documentation and interact with
-the API by visiting: http://localhost:7777/docs
+### Debugging
+The application logs detailed information about:
+- Widget data processing
+- AI model selection (DeepSeek vs Perplexity)
+- API calls and responses
+- Error handling and fallbacks
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License.