Build a District Cooling Primary-Secondary Bypass Flow Validator — implementation

## Build
Analyze tenant chilled water plate heat exchanger bypass submittals in Arabic and English. Verify decoupling line sizing against EnergyPlus primary-secondary loop guidelines to prevent thermal degradation and preserve network capacity.

## User
District Cooling Interconnection Specialist

## Workflow
1. Ingest tenant building cooling plant decoupling line specifications and bypass flow schedules in Arabic and English.
2. Calculate bypass hydraulic flow ratios against district cooling primary network loop capacities.
3. Simulate tenant building part-load bypass thermal mixing using EnergyPlus epJSON primary-secondary loop sizing outputs.
4. Compile an Arabic-English mechanical handover memorandum flagging primary-secondary bypass mixing risks.

## Interface
Web submission portal displaying tenant submittal tables, decoupling line compliance badges, and parallel language technical findings.

## Data
Construct synthetic tenant handover documents, explicitly labeled as simplified synthetic app records, including design tons, bypass flow rates, and heat exchanger curves.
Starter examples below are synthetic. They are not downloaded records.

## Source
[EnergyPlus](https://raw.githubusercontent.com/NREL/EnergyPlus/develop/README.md)
Extracts cooling coil bypass and decoupling flow sizing guidelines defined in EnergyPlus documentation to audit tenant submittals.

## Tools
dspy, pydantic, fastapi.
DSPy compiles robust prompt programs to extract and translate technical MEP parameters into structured bilingual verification records.
Hosted Claude API for consistent technical terminology mapping across Arabic and English.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Calculates mixed_return_temp_c as secondary_return_temp_c minus (bypass_flow_lps multiplied by 0.2) and flags if less than 10.0 degrees Celsius.
- Extracts decoupling pipe diameter and flow velocity, comparing against network limits.
- Generates a dual-language handover audit memo with explicit acceptance recommendations.

## Starter Examples
```json
[
  {
    "input": {
      "submittal_ref": "SUB-BP-104",
      "tenant_name_ar": "شركة الأفق للتجارة",
      "tenant_name_en": "Al-Ufuq Trading Co",
      "secondary_return_temp_c": 11,
      "bypass_flow_lps": 15,
      "decoupling_pipe_velocity_ms": 2.5
    },
    "expected_output": {
      "mixed_return_temp_c": 8,
      "compliant": false,
      "flagged_issue_en": "Bypass thermal mixing violation: mixed return temperature too low, minimum is 10.0 C",
      "flagged_issue_ar": "مخالفة الخلط الحراري: درجة حرارة الماء الراجع المخلوط منخفضة جداً، الحد الأدنى 10.0 مئوية",
      "status": "REJECTED_WITH_COMMENTS"
    }
  },
  {
    "input": {
      "submittal_ref": "SUB-BP-105",
      "tenant_name_ar": "مركز الواحة المالي",
      "tenant_name_en": "Al-Waha Financial Center",
      "secondary_return_temp_c": 14.5,
      "bypass_flow_lps": 2,
      "decoupling_pipe_velocity_ms": 0.8
    },
    "expected_output": {
      "mixed_return_temp_c": 14.1,
      "compliant": true,
      "flagged_issue_en": "None",
      "flagged_issue_ar": "لا يوجد",
      "status": "APPROVED_FOR_COMMISSIONING"
    }
  }
]
```

## Safety
District cooling approvals generated are advisory; final network connection valves must be unlocked only after field testing by utility staff.
Use mock external writes. Require human review before any real deployment.