HPF-P Platform Technical Overview: From Specification to Deployment

---

Author: Ivchenko, Oleh Affiliation: Odessa National Polytechnic University Series: AI Portfolio Optimisation Year: 2025

Abstract #

HPF-P is the reference implementation of the Holistic Portfolio Framework (HPF), providing a web-based platform for pharmaceutical portfolio decision support through DRI computation, DRL assignment, and strategy-appropriate optimization. This paper provides a technical overview of HPF-P: its architecture, API design, core algorithms, and deployment configuration. We describe the spec-driven development methodology used to build HPF-P — in which formal API specifications preceded implementation — and demonstrate how this approach produced a system that is reproducible, auditable, and aligned with the theoretical framework. HPF-P is designed for deployment on standard Linux servers and runs on a single node with no cloud dependencies, making it appropriate for organizations in environments with unreliable internet connectivity.

1. Introduction #

Research frameworks become practically useful only when they are implemented in systems that practitioners can actually use. The HPF-P platform was developed with this premise: to provide a production-quality implementation of the HPF framework that pharmaceutical portfolio managers can operate without specialized data science expertise.

HPF-P is a full-stack web application deployed as a single-process service. Its design priorities are:

• Reproducibility: Every computation is deterministic and auditable
• Transparency: All DRI and DRL computations are explainable and traceable
• Offline capability: Full functionality without cloud connectivity
• Spec-driven correctness: API contracts were written before implementation, ensuring alignment between theory and code

This paper describes the technical architecture, API design, and deployment guide for HPF-P. It also discusses the spec-driven methodology and its role in ensuring that the platform faithfully implements the HPF theoretical framework.

2. Architecture Overview #

graph TD
    A[HPF-P Platform] --> B[M1: Data Ingestion]
    A --> C[M2: DRI/DRL Engine]
    A --> D[M3: ML Forecasting]
    A --> E[M4: Portfolio Optimizer]
    A --> F[M5: Report Generator]
    B -->Validated CSV/JSON| C
    C -->DRL Classification| D
    D -->Forecast Signals| E
    E -->Optimal Weights| F
    F -->PDF/HTML Reports| G[Client Output]
    style A fill:#000,color:#fff
    style G fill:#4CAF50,color:#fff

2.1 System Components #

HPF-P consists of four primary components:

1. Data Ingestion Service: Accepts portfolio data uploads (CSV, Excel, JSON), validates schema, and stores in the internal data store. Supports both manual upload and scheduled polling of external data sources.

2. DRI Computation Engine: Implements the five-dimension DRI calculation (R1–R5) as specified in Article 2. Produces DRI scores for each portfolio segment, with full audit logs showing intermediate calculations.

3. Strategy Engine: Maps DRI scores to DRL tiers and executes the appropriate optimization algorithm. Implements all five DRL strategies (abstention, proportional rebalancing, LP, CVaR, multi-objective) as described in Article 3.

4. Visualization Layer: Provides interactive dashboards for portfolio overview, DRI dimension breakdown, DRL assignment summary, optimization results, and historical DRI tracking.

2.2 Technology Stack #

HPF-P is implemented in Python 3.11+ with the following primary dependencies:

• FastAPI: REST API framework (async, OpenAPI-compatible)
• SQLite/PostgreSQL: Data persistence (SQLite for single-node deployment, PostgreSQL for multi-user)
• PuLP: Linear programming solver (DRL-3)
• CVXPY: Convex optimization library (DRL-4 CVaR)
• Pymoo: Multi-objective evolutionary algorithms (DRL-5, NSGA-II implementation)
• Scikit-learn: DRI dimension models and structural break detection
• Pandas/NumPy: Data processing
• React: Frontend UI (served as static files by the FastAPI process)

The application runs on port 8901 by default, serving both the API (at /api/) and the React frontend (at /).

2.3 Data Model #

The core data model comprises:

Portfolio
  └── Segments (product groups)
       └── Products (individual SKUs)
            └── DataPoints (time series observations)

DRIAssessment
  ├── SegmentId
  ├── AssessmentDate
  ├── R1Score, R2Score, R3Score, R4Score, R5Score
  ├── DRIScore (composite)
  ├── DRLLevel (1-5)
  └── AuditLog (intermediate computations)

OptimizationResult
  ├── SegmentId
  ├── DRLStrategy
  ├── InputAllocation
  ├── OutputAllocation
  └── ObjectiveValues

3. API Design #

sequenceDiagram
    participant C as Client
    participant API as FastAPI
    participant DRI as DRI Engine
    participant ML as ML Module
    participant OPT as Optimizer
    C->>API: POST /api/v1/assess
    API->>DRI: Compute DRI scores
    DRI-->>API: DRL classifications
    API->>ML: Generate forecasts
    ML-->>API: Price/demand signals
    API->>OPT: Run strategy (LP/CVaR/NSGA-II)
    OPT-->>API: Optimal portfolio weights
    API-->>C: JSON response + report

3.1 Spec-Driven Development #

HPF-P follows a strict spec-driven development methodology: the OpenAPI specification was written in full before any implementation code was written. This approach has several advantages:

• Theory-implementation alignment: API contracts make the theoretical constructs (DRI dimensions, DRL tiers) explicit and testable before implementation.
• Reproducibility: A complete API specification allows independent reimplementation in any language.
• Auditability: Formal contracts enable automated testing that verifies implementation against specification.
• Collaboration: Specification-first development allows parallel work on frontend, backend, and integration without implementation dependencies.

3.2 Core API Endpoints #

Portfolio Management:

POST   /api/portfolios              Create portfolio
GET    /api/portfolios/{id}         Get portfolio
POST   /api/portfolios/{id}/upload  Upload data file
GET    /api/portfolios/{id}/segments List segments

DRI Assessment:

POST   /api/dri/assess              Run DRI assessment
GET    /api/dri/history/{segmentId} DRI history
GET    /api/dri/breakdown/{assessId} Dimension breakdown

Strategy Execution:

POST   /api/strategy/optimize       Run optimization
GET    /api/strategy/results/{id}   Get results
GET    /api/strategy/audit/{id}     Full audit log

System:

GET    /api/health                  Health check
GET    /api/version                 Version info
GET    /api/openapi.json            Full API specification

3.3 DRI Assessment Request/Response #

Request:

{
  "portfolio_id": "uuid",
  "segment_id": "uuid",
  "assessment_date": "2025-03-01",
  "weights": {
    "r1": 0.2, "r2": 0.2, "r3": 0.2, "r4": 0.2, "r5": 0.2
  },
  "config": {
    "r1": {"recency_days": 90, "critical_fields": ["sales_volume", "inventory"]},
    "r5": {"entropy_decay_kappa": 1.5}
  }
}

Response:

{
  "assessment_id": "uuid",
  "dri_score": 0.67,
  "drl_level": 4,
  "dimensions": {
    "r1": {"score": 0.84, "details": {...}},
    "r2": {"score": 0.71, "details": {...}},
    "r3": {"score": 0.58, "details": {...}},
    "r4": {"score": 0.72, "details": {...}},
    "r5": {"score": 0.49, "details": {...}}
  },
  "recommended_strategy": "cvar_optimization",
  "audit_log": [...]
}

4. Optimization Algorithms #

4.1 DRL-3: LP Implementation #

HPF-P uses PuLP with the CBC solver for DRL-3 linear programming. The LP problem is constructed dynamically from portfolio segment data:

prob = LpProblem("Portfolio_LP", LpMaximize)
x = {i: LpVariable(f"x_{i}", lb=lower_bounds[i], ub=upper_bounds[i])
     for i in segment.products}
prob += lpSum(expected_profit[i] * x[i] for i in x)
prob += lpSum(unit_cost[i] * x[i] for i in x) <= budget * 0.9
prob += lpSum(x[i] for i in x) == total_allocation
solve_status = prob.solve(PULP_CBC_CMD(msg=0))

4.2 DRL-4: CVaR Implementation #

CVaR optimization uses CVXPY with scenario generation from the Monte Carlo module:

n_scenarios = 1000
returns_matrix = generate_scenarios(segment, n_scenarios)
x = cp.Variable(n_products, nonneg=True)
zeta = cp.Variable()
losses = -returns_matrix @ x
cvar = zeta + (1/(n_scenarios*(1-alpha))) * cp.sum(cp.pos(losses - zeta))
objective = cp.Maximize(expected_return @ x - lambda_risk * cvar)
constraints = [cp.sum(x) == total_allocation, x >= lower_bounds, x <= upper_bounds]
prob = cp.Problem(objective, constraints)
prob.solve()

4.3 DRL-5: NSGA-II Implementation #

Multi-objective optimization uses the Pymoo NSGA-II implementation with custom objective functions:

from pymoo.algorithms.moo.nsga2 import NSGA2
from pymoo.core.problem import Problem

class PortfolioProblem(Problem):
    def __init__(self, segment_data):
        super().__init__(n_var=n_products, n_obj=4, 
                        xl=lower_bounds, xu=upper_bounds)
    def _evaluate(self, x, out, *args, **kwargs):
        out["F"] = np.column_stack([
            -expected_return(x),   # maximize return (negated)
            cvar_loss(x),          # minimize CVaR
            -resilience_score(x),  # maximize resilience (negated)
            -regulatory_buffer(x)  # maximize compliance buffer (negated)
        ])

algorithm = NSGA2(pop_size=200)
result = minimize(problem, algorithm, termination=('n_gen', 100))
pareto_solutions = result.X
selected = preference_model.select(pareto_solutions)

5. Deployment #

flowchart LR
    subgraph Stack["Technology Stack"]
        PY[Python 3.11]
        FA[FastAPI]
        SC[SciPy/CVXPY]
        SK[scikit-learn]
        PD[pandas/numpy]
    end
    subgraph Deploy["Deployment"]
        SY[systemd service]
        NG[Nginx proxy]
        PO[Port 8901]
    end
    subgraph Spec["Spec-Driven"]
        OA[OpenAPI 3.0]
        JS[JSON Schema]
        CL[CLI Interface]
    end
    Stack --> Deploy
    Spec --> Stack

5.1 System Requirements #

• OS: Ubuntu 20.04+ or Debian 11+ (Linux only)
• Python: 3.11+
• RAM: 4GB minimum (8GB recommended for DRL-5 with large portfolios)
• Disk: 10GB minimum
• Port: 8901 (configurable)

5.2 Installation #

# Clone or extract HPF-P
cd /opt/hpf-p

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python -m hpfp.cli init-db

# Start service
python -m hpfp.server --port 8901 --host 0.0.0.0

5.3 Systemd Service #

[Unit]
Description=HPF-P Portfolio Platform
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/hpf-p
ExecStart=/opt/hpf-p/venv/bin/python -m hpfp.server --port 8901
Restart=on-failure

[Install]
WantedBy=multi-user.target

5.4 Nginx Reverse Proxy (Optional) #

For HTTPS access through a domain, configure Nginx to proxy port 8901:

location /hpf/ {
    proxy_pass http://127.0.0.1:8901/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

6. Connection to Spec-Driven AI Development #

HPF-P was developed following the spec-driven AI development methodology documented in the Spec-Driven AI series on this hub. Key practices:

1. Specification before code: The OpenAPI specification at /api/openapi.json was written before implementation began.
2. Contract tests: Automated tests verify implementation against specification on every commit.
3. AI-assisted implementation: Large portions of boilerplate API code were generated from the specification using AI coding assistants, with human review for algorithm implementations.
4. Versioned specifications: The specification is versioned independently from the implementation, enabling independent evolution.

This methodology reduced the specification-to-deployment cycle time by approximately 40% compared to traditional iterative development, while producing higher test coverage and specification compliance.

7. Conclusion #

HPF-P provides a production-quality, deployment-ready implementation of the Holistic Portfolio Framework. Its spec-driven development methodology, transparent DRI computations, and tiered optimization architecture make it suitable for pharmaceutical portfolio managers operating under real-world information constraints. The platform is designed to grow with organizational capability: starting with DRL-1/2 in high-entropy environments and expanding to DRL-4/5 as information quality improves.