PL Capital — Portfolio Analytics Agent: Technical Document

1. Project Overview

PL Capital Portfolio Analytics Agent is an AI-powered natural language interface for investment portfolio analytics. It allows users to ask plain-English questions about portfolios, holdings, performance, risk, and sector exposure — and receive accurate, structured answers without writing SQL or financial formulas.

2. Project Structure

PL Capital/
├── main.py                        # CLI entry point (interactive loop)
├── requirements.txt               # Python dependencies
├── .env                           # API keys (not committed)
├── README.md                      # Brief document of the project
│
├── portfolio_agent/               # Core agent package
│   ├── __init__.py                # Exports PortfolioAgent
│   ├── agent.py                   # PortfolioAgent class
│   ├── config.py                  # Env-based configuration
│   ├── prompts.py                 # System & narration prompt templates
│   └── tools/
│       ├── __init__.py
│       ├── sql_tool.py            # SQL execution tool
│       └── exposure_tool.py       # Sector exposure calculator
│
├── app/
│   └── streamlit_app.py           # Browser-based chat UI
│
├── scripts/
│   ├── load_db.py                 # DB initialisation from CSV files
│   └── evaluate.py                # Ground-truth evaluation runner
│
├── schema/
│   └── database_schema.sql        # DDL: tables, indices, constraints
│
├── data/                          # Seed CSV files
│   ├── portfolios.csv
│   ├── securities.csv
│   ├── sectors.csv
│   ├── holdings.csv
│   ├── benchmarks.csv
│   ├── transactions.csv
│   ├── historical_prices.csv
│   ├── portfolio_performance.csv
│   └── risk_metrics.csv
│
└── ground_truth_dataset.json      # 10 labelled Q&A pairs for evaluation

---

3. Agent Workflow

ask(question)
    │
    ├─ Build messages: [system_prompt, user_question]
    │
    ├─ Gemini Turn 1 (with tool definitions)
    │       └─ Returns: function_call { name, args }
    │
    ├─ Tool Dispatch
    │       ├─ "execute_sql"          → SqlTool.run(sql)
    │       └─ "exposure_calculator"  → ExposureTool.run(portfolio_name)
    │
    ├─ Append tool result to message history
    │
    ├─ Gemini Turn 2 (narration only, no tools)
    │       └─ Returns: natural language answer
    │
    └─ Return final answer string

---

4. Setup & Installation

Prerequisites

• Python 3.10 or higher
• A Google Gemini API key (ai.google.dev)

Steps

# 1. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate          # macOS/Linux
venv\Scripts\activate             # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment
# Edit .env and set:
# GEMINI_API_KEY=your_api_key_here

# 4. Initialise the database
python scripts/load_db.py

After load_db.py completes, portfolio_database.db is created in the project root, populated with all seed data.

---

5. Running the Application

CLI (Interactive Mode)

python main.py

Type any natural language question at the prompt. Enter quit or exit to stop.

> How many portfolios are currently active?
There are 4 active portfolios.

> What is the sector exposure of the Tech Innovation Fund?
The Tech Innovation Fund has the following sector exposure:
  - Technology:  72.4%
  - Consumer:    18.1%
  - Financials:   9.5%

Web UI (Streamlit)

streamlit run app/streamlit_app.py

Opens a browser-based chat interface at http://localhost:8501 with:

• Example question buttons for quick testing.
• Chat history display.
• SQL query and result visualisation panels.
• Altair charts for sector breakdowns.

---

6. Evaluation

The project includes a formal evaluation suite against 10 labelled ground-truth question-answer pairs.

# Run evaluation (summary output)
python scripts/evaluate.py

# Verbose output (per-question details)
python scripts/evaluate.py --verbose

Evaluation Output

Results are printed to the terminal and saved to a JSON file. Metrics reported:

• Per-question PASS / FAIL.
• Overall accuracy percentage.
• Tool selection accuracy.
• SQL correctness (where applicable).

---