# TEI Tool

The **TEI (Total Economic Impact) Tool** provides a configurable financial calculator for building client-specific business cases. It attaches to an existing Proposal or Engagement, inheriting client context (company name, industry, etc.) without redundant data entry, and exposes a REST API consumed by Streamlit calculators and LLM report-generation pipelines.

---

## Overview

Two parent objects define a TEI calculation:

- **TEIReport** (admin-configured template) — defines the field schema, analysis period, and discount rate. Created once per study type (e.g., "Amazon Connect 2026"). Multiple tools share one report.
- **TEITool** (one per client opportunity) — holds the actual values, financial summary, and version history. Inherits `name`, `description`, `owner`, `subscriber`, `proposal`, `engagement`, and `is_active` from {py:class}`core.models.BaseTool`.

The tool lifecycle is: **create → seed values → edit values → calculate → save version → export**.

---

## Data Model

| Model | Role |
|-------|------|
| `TEIReport` | Admin template: field schema + financial parameters |
| `TEIReportField` | One field definition (benefit or cost) on a report |
| `TEITool` | A specific calculation attached to a Proposal/Engagement |
| `TEIFieldValue` | Current value for one field, one year (or null for non-annual) |
| `TEIFinancialSummary` | Fixed-schema rollup (1-to-1 with a tool); written by `/calculate/` |
| `TEIVersion` | Immutable JSON snapshot of values + summary at a point in time |

**Public identifiers:** `TEIReport`, `TEITool`, and `TEIVersion` are addressed by a 12-character short UUID (`public_id`) in all API URLs. `TEIReportField` is addressed by its integer PK under its parent report's `public_id`.

---

## API Base URL and Authentication

```
/api/v1/tei/
```

All endpoints require `IsAuthenticated`. The error envelope is always:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": [...]
  }
}
```

### Permissions

| Operation | Admin | Consultant | Viewer |
|-----------|:-----:|:----------:|:------:|
| Create/edit/delete Reports and Fields | Yes | No | No |
| Create TEITool | Yes | Yes | No |
| Edit values, trigger calculation, save version | Yes | Yes | No |
| View tools, values, summary, versions, export | Yes | Yes | Yes |
| Delete TEITool | Yes | Yes (own only) | No |

Data isolation follows the parent Proposal/Engagement — if a user cannot see the Proposal, they cannot see the attached TEI tool.

---

## Reports (admin)

Reports are read-only for consultants; admins manage them.

### List / Create

```
GET  /api/v1/tei/reports/
POST /api/v1/tei/reports/
```

**Query params (GET):** `status` (`draft` | `active` | `archived`), `vendor`

**POST body:**

```json
{
  "name": "Amazon Connect 2026",
  "vendor": "AWS",
  "version": "1.0",
  "description": "Based on Forrester TEI February 2026",
  "analysis_period_years": 3,
  "discount_rate": "0.10",
  "status": "draft"
}
```

**Response shape (list item):**

```json
{
  "id": "Ab3Cd5Ef7Gh9",
  "name": "Amazon Connect 2026",
  "vendor": "AWS",
  "version": "1.0",
  "description": "...",
  "analysis_period_years": 3,
  "discount_rate": "0.1000",
  "status": "active",
  "field_count": 12,
  "instance_count": 3,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}
```

### Detail / Update / Delete

```
GET    /api/v1/tei/reports/{report_id}/
PUT    /api/v1/tei/reports/{report_id}/
PATCH  /api/v1/tei/reports/{report_id}/
DELETE /api/v1/tei/reports/{report_id}/
```

**Business rules:**
- `DELETE` is only allowed when `status = draft` and no tools exist (`instance_count = 0`).
- `analysis_period_years` cannot be changed if any tools reference this report — raises `409 MODEL_HAS_INSTANCES`.

---

## Report Fields (admin)

Fields define what the calculator collects. They are nested under their parent report.

### List / Add

```
GET  /api/v1/tei/reports/{report_id}/fields/
POST /api/v1/tei/reports/{report_id}/fields/
```

**Query params (GET):** `table` (`benefits` | `costs`), `category`

**POST body:**

```json
{
  "table": "benefits",
  "field_key": "ai_resolution_efficiency",
  "label": "AI-Driven Contact Resolution Efficiency",
  "description": "Labor savings from AI-powered self-service",
  "field_type": "currency",
  "category": "AI Resolution",
  "default_value": null,
  "is_annual": true,
  "risk_adjustment": "0.20",
  "sort_order": 1,
  "is_required": true,
  "source_notes": "Forrester TEI 2026 — $64.3M over 3 years"
}
```

`field_type` choices: `currency`, `percentage`, `integer`, `decimal`, `text`

Adding a field to a report that already has tools will back-fill `TEIFieldValue` rows (null values) for every existing tool.

### Update / Delete

```
PUT    /api/v1/tei/reports/{report_id}/fields/{field_id}/
PATCH  /api/v1/tei/reports/{report_id}/fields/{field_id}/
DELETE /api/v1/tei/reports/{report_id}/fields/{field_id}/?confirm=true
```

**Protected fields** — once any tool has values for a field, these attributes are immutable (raises `409 PROTECTED_FIELD`):
- `field_key`
- `field_type`
- `is_annual`

Always mutable: `label`, `description`, `default_value`, `risk_adjustment`, `sort_order`, `category`, `source_notes`.

`DELETE` requires `?confirm=true` and cascades all `TEIFieldValue` rows for that field across every tool. Historical version snapshots are unaffected (they are stored as JSON).

### Reorder

```
PATCH /api/v1/tei/reports/{report_id}/fields/reorder/
```

```json
{
  "field_order": [
    {"id": 1, "sort_order": 1},
    {"id": 2, "sort_order": 2}
  ]
}
```

---

## Tools

A tool is one TEI calculation attached to one Proposal or Engagement.

### List / Create

```
GET  /api/v1/tei/tools/
POST /api/v1/tei/tools/
```

**Query params (GET):** `status`, `report` (report `public_id`), `proposal` (PK), `engagement` (PK)

**POST body:**

```json
{
  "report": "Ab3Cd5Ef7Gh9",
  "proposal": 42,
  "name": null,
  "status": "draft"
}
```

Supply exactly one of `proposal` or `engagement`. `name` defaults to the report name when omitted.

**Side effects on create:**
- Creates `TEIFieldValue` rows for every field in the report (populated from `default_value`, or empty string).
- For annual fields, creates one row per year (1 through `analysis_period_years`).
- Creates an empty `TEIFinancialSummary` record.

A duplicate active tool for the same report + proposal/engagement raises `409 DUPLICATE_INSTANCE`.

### Detail / Update / Delete

```
GET    /api/v1/tei/tools/{tool_id}/
PUT    /api/v1/tei/tools/{tool_id}/
PATCH  /api/v1/tei/tools/{tool_id}/
DELETE /api/v1/tei/tools/{tool_id}/?confirm=true
```

Only `name` and `status` are mutable via `PUT`/`PATCH`. `DELETE` requires `?confirm=true` and cascades all values, versions, and summary.

**Tool detail response:**

```json
{
  "id": "Xy1Za2Bc3De4",
  "report": {
    "id": "Ab3Cd5Ef7Gh9",
    "name": "Amazon Connect 2026",
    "vendor": "AWS",
    "version": "1.0",
    "analysis_period_years": 3,
    "discount_rate": "0.1000"
  },
  "opportunity": {
    "id": "...",
    "name": "Acme Corp CX Transformation",
    "proposal_id": "...",
    "client": {
      "id": "...",
      "name": "Acme Corporation",
      "short_name": "Acme"
    }
  },
  "engagement": null,
  "name": "Amazon Connect 2026",
  "status": "in_progress",
  "current_version": 2,
  "summary": {
    "net_present_value": "14200000.00",
    "roi_percentage": "289.8000",
    "total_benefits_pv": "19100000.00",
    "total_costs_pv": "4900000.00"
  },
  "created_date": "2025-01-20T14:30:00Z",
  "modified_date": "2025-02-03T09:15:00Z"
}
```

---

## Values

### Get all values

```
GET /api/v1/tei/tools/{tool_id}/values/
```

**Query params:** `table` (`benefits` | `costs`), `category`

Annual fields return a `years` object; non-annual fields return a flat `value`:

```json
{
  "tool_id": "Xy1Za2Bc3De4",
  "report": "Amazon Connect 2026",
  "values": [
    {
      "id": 1,
      "field_key": "ai_resolution_efficiency",
      "label": "AI-Driven Contact Resolution Efficiency",
      "table": "benefits",
      "category": "AI Resolution",
      "field_type": "currency",
      "is_annual": true,
      "risk_adjustment": "0.20",
      "years": {
        "1": {"value": "12500000.00", "risk_adjustment": null, "notes": ""},
        "2": {"value": "24800000.00", "risk_adjustment": null, "notes": ""},
        "3": {"value": "27000000.00", "risk_adjustment": "0.25", "notes": "Phase 3 risk"}
      }
    },
    {
      "id": 2,
      "field_key": "legacy_termination",
      "label": "Legacy Solution Termination Fees",
      "table": "costs",
      "category": "Migration",
      "field_type": "currency",
      "is_annual": false,
      "risk_adjustment": null,
      "value": "1200000.00",
      "notes": "Confirmed by procurement"
    }
  ]
}
```

### Bulk update

```
PUT /api/v1/tei/tools/{tool_id}/values/
```

```json
{
  "values": [
    {"field_key": "ai_resolution_efficiency", "year": 1, "value": "12500000.00", "risk_adjustment": null, "notes": null},
    {"field_key": "ai_resolution_efficiency", "year": 2, "value": "24800000.00", "risk_adjustment": null, "notes": "60% containment by month 18"},
    {"field_key": "legacy_termination", "year": null, "value": "1200000.00", "risk_adjustment": null, "notes": null}
  ]
}
```

- `year` must be `null` for non-annual fields, `1..N` for annual fields.
- Validation raises `400 INVALID_FIELD_KEY`, `400 INVALID_YEAR`, or `400 TYPE_MISMATCH` on bad input.
- Does **not** auto-recalculate — call `/calculate/` explicitly.
- Returns the same shape as `GET /values/`.

### Update single value

```
PATCH /api/v1/tei/tools/{tool_id}/values/{field_key}/?year=1
```

```json
{
  "value": "13000000.00",
  "risk_adjustment": "0.15",
  "notes": "Revised after benchmarking call"
}
```

`?year` is required for annual fields; omit (or pass `year=null`) for non-annual fields.

---

## Calculation

```
POST /api/v1/tei/tools/{tool_id}/calculate/
```

No request body. Uses current stored values. Persists result in `TEIFinancialSummary` (upsert).

**Response:**

```json
{
  "total_benefits_pv": "19100000.00",
  "total_costs_pv": "4900000.00",
  "net_present_value": "14200000.00",
  "roi_percentage": "289.8000",
  "payback_period_months": 8,
  "total_benefits_nominal": "22300000.00",
  "total_costs_nominal": "5400000.00",
  "benefits_year_1": "5200000.00",
  "benefits_year_2": "9800000.00",
  "benefits_year_3": "7300000.00",
  "costs_year_1": "3800000.00",
  "costs_year_2": "900000.00",
  "costs_year_3": "700000.00",
  "discount_rate": "0.1000",
  "calculated_at": "2025-02-03T09:15:00Z"
}
```

---

## Summary

```
GET /api/v1/tei/tools/{tool_id}/summary/
```

Returns the stored `TEIFinancialSummary` in the same shape as the `/calculate/` response. Returns `404 SUMMARY_NOT_CALCULATED` if `/calculate/` has never been called.

---

## Versions

Versions are **immutable** snapshots. They cannot be updated or deleted via the API.

### List

```
GET /api/v1/tei/tools/{tool_id}/versions/
```

Returns headline summary only (NPV + ROI) per version item.

### Save new version

```
POST /api/v1/tei/tools/{tool_id}/versions/
```

```json
{
  "date": "2025-02-03",
  "note": "Updated with actuals from finance team. Containment revised to 24%."
}
```

**Side effects:**
1. Auto-triggers `/calculate/` to ensure the summary is current.
2. Snapshots all current `TEIFieldValue` rows as JSON into `values_snapshot`.
3. Snapshots current `TEIFinancialSummary` as JSON into `summary_snapshot`.
4. Increments `tool.current_version`.

Returns the created version (without full snapshots — use the detail endpoint to retrieve those).

### Version detail

```
GET /api/v1/tei/tools/{tool_id}/versions/{version_number}/
```

Returns full `values_snapshot` and `summary_snapshot`.

---

## Export (LLM payload)

```
GET /api/v1/tei/tools/{tool_id}/export/
```

Returns everything needed for LLM report generation in one payload. Auto-recalculates before building the response.

**Response shape:**

```json
{
  "export_date": "2025-02-03T09:30:00Z",
  "client": {
    "name": "Acme Corporation",
    "short_name": "Acme",
    "industry": "Financial Services",
    "size": "enterprise"
  },
  "opportunity": {
    "name": "CX Transformation",
    "stage": "proposal"
  },
  "engagement": null,
  "report": {
    "name": "Amazon Connect 2026",
    "vendor": "AWS",
    "version": "1.0",
    "analysis_period_years": 3,
    "discount_rate": "0.10"
  },
  "benefits": [
    {
      "field_key": "ai_resolution_efficiency",
      "label": "AI-Driven Contact Resolution Efficiency",
      "category": "AI Resolution",
      "risk_adjustment": "0.20",
      "source_notes": "Forrester TEI 2026 — $64.3M over 3 years",
      "years": {
        "1": {"nominal": "12500000.00", "risk_adjusted": "10000000.00"},
        "2": {"nominal": "24800000.00", "risk_adjusted": "19840000.00"},
        "3": {"nominal": "27000000.00", "risk_adjusted": "20250000.00"}
      },
      "total_nominal": "64300000.00",
      "total_risk_adjusted": "50090000.00",
      "present_value": "41200000.00"
    }
  ],
  "costs": [
    {
      "field_key": "connect_licensing",
      "label": "Amazon Connect Licensing & Usage",
      "category": "Platform",
      "source_notes": "Per-minute pricing model",
      "years": {
        "1": {"value": "2000000.00"},
        "2": {"value": "2200000.00"},
        "3": {"value": "2400000.00"}
      },
      "total_nominal": "6600000.00",
      "present_value": "5490000.00"
    }
  ],
  "summary": {
    "total_benefits_pv": "19100000.00",
    "total_costs_pv": "4900000.00",
    "net_present_value": "14200000.00",
    "roi_percentage": "289.80",
    "payback_period_months": 8
  },
  "versions": [
    {"version_number": 2, "date": "2025-02-03", "note": "Actuals from finance team"},
    {"version_number": 1, "date": "2025-01-15", "note": "Initial Forrester defaults"}
  ]
}
```

Non-annual cost fields appear under `"years": {"1": {"value": "..."}}` (treated as Year 1).

---

## Cross-Tool Rollup

```
GET /api/v1/tei/summary/
```

**Query params:** `status`, `vendor`, `min_npv`

Returns aggregate NPV across all calculated tools plus per-tool headline rows. Only includes tools where `/calculate/` has been run at least once.

---

## Jupyter Notebook Workflow

A typical notebook session using the TEI API:

```python
import requests

BASE = "https://athena.example.com/api/v1/tei"
HEADERS = {"Authorization": "Token <your-token>"}
TOOL_ID = "Xy1Za2Bc3De4"   # TEITool public_id

# 1. Load tool metadata and client context
tool = requests.get(f"{BASE}/tools/{TOOL_ID}/", headers=HEADERS).json()

# 2. Load current values (benefits + costs)
values_resp = requests.get(f"{BASE}/tools/{TOOL_ID}/values/", headers=HEADERS).json()
values = values_resp["values"]

# 3. Update values (customize for the client)
updated_rows = [
    {"field_key": "ai_resolution_efficiency", "year": 1, "value": "11000000.00"},
    {"field_key": "ai_resolution_efficiency", "year": 2, "value": "23000000.00"},
    {"field_key": "ai_resolution_efficiency", "year": 3, "value": "25500000.00"},
    {"field_key": "legacy_termination", "year": None, "value": "950000.00"},
]
requests.put(
    f"{BASE}/tools/{TOOL_ID}/values/",
    headers=HEADERS,
    json={"values": updated_rows},
)

# 4. Recalculate
summary = requests.post(f"{BASE}/tools/{TOOL_ID}/calculate/", headers=HEADERS).json()
print(f"NPV: {summary['net_present_value']}, ROI: {summary['roi_percentage']}%")

# 5. Save a version snapshot
requests.post(
    f"{BASE}/tools/{TOOL_ID}/versions/",
    headers=HEADERS,
    json={"date": "2025-02-03", "note": "Notebook scenario — conservative containment"},
)

# 6. Get the full LLM-ready export
export = requests.get(f"{BASE}/tools/{TOOL_ID}/export/", headers=HEADERS).json()
# export["benefits"], export["costs"], export["summary"] are all populated
```

### Finding the tool_id

If you know the Proposal PK or Engagement PK:

```python
tools = requests.get(
    f"{BASE}/tools/",
    headers=HEADERS,
    params={"proposal": 42, "status": "in_progress"},
).json()
tool_id = tools["results"][0]["id"]
```

If the tool doesn't exist yet, create it first:

```python
new_tool = requests.post(
    f"{BASE}/tools/",
    headers=HEADERS,
    json={"report": "Ab3Cd5Ef7Gh9", "proposal": 42},
).json()
tool_id = new_tool["id"]
```

---

## Calculation Logic Reference

### Benefit risk adjustment

```
risk_adjusted_value = nominal_value × (1 − risk_adjustment)
```

`risk_adjustment` comes from the `TEIFieldValue` instance override if set, otherwise from `TEIReportField.risk_adjustment`, otherwise 0. Costs are **never** risk-adjusted.

### Present value discounting

Each annual value is discounted to today:

```
PV = value / (1 + discount_rate) ^ year
```

where `year` is 1, 2, … N and `discount_rate` comes from the `TEIReport`. Non-annual (one-time) values are treated as Year 1.

### Summary calculations

```
total_benefits_nominal = sum of all risk-adjusted benefit values (all years)
total_costs_nominal    = sum of all cost values (all years)

total_benefits_pv = Σ PV(risk_adjusted_benefit, year)  for all benefit fields
total_costs_pv    = Σ PV(cost, year)                   for all cost fields

net_present_value = total_benefits_pv − total_costs_pv
roi_percentage    = (net_present_value / total_costs_pv) × 100
```

`roi_percentage` is `null` when `total_costs_pv` is 0.

### Payback period

Annual values are prorated evenly across 12 months. One-time (non-annual) values land in month 1 as a lump sum. The payback month is the first month where cumulative risk-adjusted benefits ≥ cumulative costs. Returns `null` if never achieved within `analysis_period_years`.

### Edge cases

| Scenario | Behaviour |
|----------|-----------|
| Null/blank field value | Treated as 0 |
| All benefits zero | NPV = −total_costs_pv, ROI = null if costs are also 0 |
| All costs zero | NPV = total_benefits_pv, ROI = null (division by zero) |
| `risk_adjustment = 1.0` | Benefit is zeroed out (fully excluded) |
| `risk_adjustment = 0.0` | Full nominal value used |
| Non-annual field | Folded into Year 1 for NPV and payback |

All arithmetic uses Python `Decimal` to avoid floating-point drift. Values are stored as strings and cast at calculation time.

---

## Error Codes

| HTTP | Code | When |
|------|------|------|
| 400 | `VALIDATION_ERROR` | Missing required field, wrong type |
| 400 | `INVALID_FIELD_KEY` | `field_key` not defined in the tool's report |
| 400 | `INVALID_YEAR` | Year missing for annual field, or present for non-annual, or out of range |
| 400 | `TYPE_MISMATCH` | Value cannot be parsed as the field's `field_type` |
| 401 | `AUTHENTICATION_REQUIRED` | Missing or invalid token |
| 403 | `PERMISSION_DENIED` | Role does not allow this operation |
| 404 | `NOT_FOUND` | Resource does not exist |
| 404 | `SUMMARY_NOT_CALCULATED` | `GET /summary/` before any `/calculate/` run |
| 409 | `DUPLICATE_INSTANCE` | Creating a second active tool for the same report + proposal/engagement |
| 409 | `FIELD_KEY_EXISTS` | `field_key` already exists within the report |
| 409 | `PROTECTED_FIELD` | Changing `field_key`, `field_type`, or `is_annual` when values exist |
| 409 | `MODEL_HAS_INSTANCES` | Deleting a report or changing `analysis_period_years` when tools exist |
| 422 | `CALCULATION_ERROR` | Calculation failed unexpectedly |

---

*TEI Tool — Athena*