allucanget/calminer
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

Add initial implementation of CalMiner with project structure, environment setup, and core features

Browse Source 
- Create .env.example for environment variables
- Update README with project structure and development setup instructions
- Implement FastAPI application with API routes for scenarios and parameters
- Add database models for scenarios, parameters, and simulation results
- Introduce validation middleware for JSON requests
- Create services for running simulations and generating reports
- Add testing strategy and directory structure in documentation
This commit is contained in:
zwitschi
2025-10-20 18:37:57 +02:00
parent cb9749010f
commit 39c45e720c
20 changed files with 604 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
docs/implementation_plan.md
View File

@@ -1,43 +1,153 @@
# Implementation Plan
## Feature: Scenario Creation and Management
This document outlines the MVP features and implementation steps for CalMiner.
### Scenario Implementation Steps
Refer to the following for context alignment:
1. Create `models/scenario.py` for DB interactions.
2. Implement API endpoints in `routes/scenarios.py`: GET, POST, PUT, DELETE.
3. Add frontend component `components/ScenarioForm.html` for CRUD.
4. Update `README.md` with API docs.
- System architecture: [docs/architecture.md](architecture.md)
- Development setup: [docs/development_setup.md](development_setup.md)
## Feature: Parameter Input and Validation
## Project Setup
### Parameter Implementation Steps
1. Connect to PostgreSQL database with schema `calminer`.
2. Create and activate a virtual environment and install dependencies via `requirements.txt`.
3. Define environment variables in `.env`, including `DATABASE_URL`.
4. Configure FastAPI entrypoint in `main.py` to include routers.
1. Define parameter schemas in `models/parameters.py`.
2. Create validation middleware in `middleware/validation.py`.
3. Build input form in `components/ParameterInput.html`.
4. Integrate with scenario management.
## Feature: Scenario Management
## Feature: Monte Carlo Simulation Run
### Implementation Steps
### Simulation Implementation Steps
1. Create `models/scenario.py` for scenario CRUD.
2. Implement API endpoints in `routes/scenarios.py` (GET, POST, PUT, DELETE).
3. Write unit tests in `tests/unit/test_scenario.py`.
4. Build UI component `components/ScenarioForm.html`.
1. Implement simulation logic in `services/simulation.py`.
2. Add endpoint `POST /api/simulations/run`.
3. Store results in `models/simulation_result.py`.
4. Add progress tracking UI.
## Feature: Process Parameters
## Feature: Basic Reporting
### Implementation Steps
### Reporting Implementation Steps
1. Create `models/parameters.py` for process parameters.
2. Implement Pydantic schemas in `routes/parameters.py`.
3. Add validation middleware in `middleware/validation.py`.
4. Write unit tests in `tests/unit/test_parameter.py`.
5. Build UI component `components/ParameterInput.html`.
1. Create report service `services/reporting.py`.
2. Build dashboard component `components/Dashboard.html`.
3. Fetch data from simulation results.
4. Add charts using Chart.js.
## Feature: Stochastic Variables
## Next Steps
### Implementation Steps
- Assign issues in GitHub.
- Estimate effort for each step.
- Start with backend models.
1. Create `models/distribution.py` for variable distributions.
2. Implement API routes in `routes/distributions.py`.
3. Write Pydantic schemas and validations.
4. Write unit tests in `tests/unit/test_distribution.py`.
5. Build UI component `components/DistributionEditor.html`.
## Feature: Cost Tracking
### Implementation Steps
1. Create `models/capex.py` and `models/opex.py`.
2. Implement API routes in `routes/costs.py`.
3. Write Pydantic schemas for CAPEX/OPEX.
4. Write unit tests in `tests/unit/test_costs.py`.
5. Build UI component `components/CostForm.html`.
## Feature: Consumption Tracking
### Implementation Steps
1. Create models for consumption: `chemical_consumption.py`, `fuel_consumption.py`, `water_consumption.py`, `scrap_consumption.py`.
2. Implement API routes in `routes/consumption.py`.
3. Write Pydantic schemas for consumption data.
4. Write unit tests in `tests/unit/test_consumption.py`.
5. Build UI component `components/ConsumptionDashboard.html`.
## Feature: Production Output
### Implementation Steps
1. Create `models/production_output.py`.
2. Implement API routes in `routes/production.py`.
3. Write Pydantic schemas for production output.
4. Write unit tests in `tests/unit/test_production.py`.
5. Build UI component `components/ProductionChart.html`.
## Feature: Equipment Management
### Implementation Steps
1. Create `models/equipment.py` for equipment data.
2. Implement API routes in `routes/equipment.py`.
3. Write Pydantic schemas for equipment.
4. Write unit tests in `tests/unit/test_equipment.py`.
5. Build UI component `components/EquipmentList.html`.
## Feature: Maintenance Logging
### Implementation Steps
1. Create `models/maintenance.py` for maintenance events.
2. Implement API routes in `routes/maintenance.py`.
3. Write Pydantic schemas for maintenance logs.
4. Write unit tests in `tests/unit/test_maintenance.py`.
5. Build UI component `components/MaintenanceLog.html`.
## Feature: Monte Carlo Simulation Engine
### Implementation Steps
1. Implement Monte Carlo logic in `services/simulation.py`.
2. Persist results in `models/simulation_result.py`.
3. Expose endpoint in `routes/simulations.py`.
4. Write integration tests in `tests/unit/test_simulation.py`.
5. Build UI component `components/SimulationRunner.html`.
## Feature: Reporting / Dashboard
### Implementation Steps
1. Implement report calculations in `services/reporting.py`.
2. Add detailed and summary endpoints in `routes/reporting.py`.
3. Write unit tests in `tests/unit/test_reporting.py`.
4. Enhance UI in `components/Dashboard.html` with charts.
## MVP Feature Analysis (summary)
Goal: Identify core MVP features, acceptance criteria, and quick estimates.
Features:
- Scenario Management
- Acceptance: create/read/update/delete scenarios; persist to DB; API coverage with tests.
- Estimate: 3-5 days (backend + minimal UI).
- Parameter Input & Validation
- Acceptance: define parameter schemas, validate inputs, surface errors to API/UI.
- Estimate: 2-3 days.
- Monte Carlo Simulation Engine
- Acceptance: run parameterised simulations, store results, ability to rerun with different seeds, basic progress reporting.
- Estimate: 1-2 weeks (core engine + persistence).
- Reporting / Dashboard
- Acceptance: display simulation outputs (NPV, IRR distributions), basic charts, export CSV.
- Estimate: 4-7 days.
Edge cases to consider:
- Large simulation runs (memory / timeouts) — use streaming, chunking, or background workers.
- DB migration and schema versioning.
- Authentication/authorization for scenario access.
Next actionable items:
1. Break Scenario Management into sub-issues (models, routes, tests, simple UI).
2. Scaffold Parameter Input & Validation (models/parameters.py, middleware, routes, tests).
3. Prototype the simulation engine with a small deterministic runner and unit tests.
4. Scaffold Monte Carlo Simulation endpoints (`services/simulation.py`, `routes/simulations.py`, tests).
5. Scaffold Reporting endpoints (`services/reporting.py`, `routes/reporting.py`, front-end Dashboard, tests).
6. Add CI job for tests and coverage.