kilowattchiaro-engine 0.1.0__tar.gz

kilowattchiaro_engine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv --python 3.12
+      - run: uv pip install -e '.[dev]'
+      - run: uv run pytest -q

kilowattchiaro_engine-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no tokens stored anywhere.
+# One-time setup on pypi.org: add a trusted publisher for project
+# kilowattchiaro-engine -> repo domenicodigangi/kilowattchiaro, workflow
+# release.yml, environment pypi.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

kilowattchiaro_engine-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/

kilowattchiaro_engine-0.1.0/.kwc-export

@@ -0,0 +1 @@
+created by build-public-repo.py — safe to regenerate

kilowattchiaro_engine-0.1.0/LICENSE.md

@@ -0,0 +1,34 @@
+# KiloWattChiaro Source-Available License
+
+**SPDX-License-Identifier: LicenseRef-KWC-Source-Available**
+
+Copyright (c) 2026 Domenico Di Gangi. All rights reserved.
+
+This source code is made public so that anyone can **read, run, and
+verify** the methodology behind the KiloWattChiaro solar evaluation —
+transparency is the product's core promise. It is *source-available*,
+not open source.
+
+**You may:**
+
+1. View, download, and run the code for personal, educational, or
+   evaluation purposes.
+2. Verify, reproduce, and publicly discuss the results and methodology,
+   with attribution.
+3. Open issues and submit patches (contributions are licensed to the
+   copyright holder under these same terms).
+
+**You may not, without prior written permission:**
+
+1. Use the code, or substantial portions of it, in a commercial product
+   or service.
+2. Redistribute, republish, or offer the code (modified or not) as a
+   library, package, or service of your own.
+3. Remove or alter attribution or this license.
+
+The software is provided "as is", without warranty of any kind, express
+or implied. No liability is accepted for any use of it — solar
+investment decisions remain your own.
+
+For commercial licensing or any permission requests:
+**kilowattchiaro@gmail.com**.

kilowattchiaro_engine-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.5
+Name: kilowattchiaro-engine
+Version: 0.1.0
+Summary: The deterministic solar-evaluation engine behind kilowattchiaro.it — NPV, IRR, payback, scenarios and historical backtests for Italian residential solar.
+Project-URL: Homepage, https://kilowattchiaro.it
+Project-URL: Repository, https://github.com/domenicodigangi/kilowattchiaro
+Project-URL: Methodology, https://github.com/domenicodigangi/kilowattchiaro/blob/master/docs/methodology.md
+Author: Domenico Di Gangi
+License: # KiloWattChiaro Source-Available License
+        
+        **SPDX-License-Identifier: LicenseRef-KWC-Source-Available**
+        
+        Copyright (c) 2026 Domenico Di Gangi. All rights reserved.
+        
+        This source code is made public so that anyone can **read, run, and
+        verify** the methodology behind the KiloWattChiaro solar evaluation —
+        transparency is the product's core promise. It is *source-available*,
+        not open source.
+        
+        **You may:**
+        
+        1. View, download, and run the code for personal, educational, or
+           evaluation purposes.
+        2. Verify, reproduce, and publicly discuss the results and methodology,
+           with attribution.
+        3. Open issues and submit patches (contributions are licensed to the
+           copyright holder under these same terms).
+        
+        **You may not, without prior written permission:**
+        
+        1. Use the code, or substantial portions of it, in a commercial product
+           or service.
+        2. Redistribute, republish, or offer the code (modified or not) as a
+           library, package, or service of your own.
+        3. Remove or alter attribution or this license.
+        
+        The software is provided "as is", without warranty of any kind, express
+        or implied. No liability is accepted for any use of it — solar
+        investment decisions remain your own.
+        
+        For commercial licensing or any permission requests:
+        **kilowattchiaro@gmail.com**.
+License-File: LICENSE.md
+Keywords: energy,irr,italy,npv,payback,photovoltaic,solar
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic[email]>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KiloWattChiaro
+
+> **The independent check on the solar purchase.**
+> Live and free at **[kilowattchiaro.it](https://kilowattchiaro.it)**.
+
+[![ci](https://github.com/domenicodigangi/kilowattchiaro/actions/workflows/ci.yml/badge.svg)](https://github.com/domenicodigangi/kilowattchiaro/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kilowattchiaro-engine)](https://pypi.org/project/kilowattchiaro-engine/)
+[![License: Source-Available](https://img.shields.io/badge/license-source--available-8a6d1a)](LICENSE.md)
+
+An Italian homeowner considering rooftop solar has two questions nobody
+neutral will answer: **is solar worth it for my house?** and **is this
+quote fair?** The market's default path runs through lead aggregators
+that resell your phone number to competing installers — everyone you can
+ask gets paid if you say yes.
+
+KiloWattChiaro is the neutral answer: a **deterministic evaluation
+engine** with a fully published methodology, an **agentic quote
+reviewer** that must back every technical claim with a manufacturer
+datasheet citation, and a hard architectural wall between the check and
+the sale — a *"solar is not worth it for your roof"* verdict is a
+first-class result, presented exactly like a yes.
+
+## What's in this repository
+
+This repo publishes the part of the product whose entire value is being
+inspectable — the code that computes every number a homeowner sees:
+
+| Public — this repo | Private — the product |
+|---|---|
+| `src/kilowattchiaro_engine/` — the deterministic evaluation engine, **exactly as deployed in production** (NPV, IRR, payback, hourly self-consumption, price scenarios, historical backtests) | Web app, HTTP service layer, persistence |
+| `tests/` — 325 tests: unit, stress, validation, and backtests across the 2011–2025 Italian incentive regimes | Booking service (separate system, no AI in it) |
+| [`docs/methodology.md`](docs/methodology.md) — the full methodology: every formula and every assumption, with values | Quote-agent runtime — in production at [kilowattchiaro.it/preventivo](https://kilowattchiaro.it/preventivo) |
+| [`docs/architecture.md`](docs/architecture.md) — system design, runtime + delivery diagrams | Component catalogue & price-benchmark data ([open rubric CSV](https://kilowattchiaro.it/open-data) is CC BY 4.0) |
+| [`docs/quote-engine.md`](docs/quote-engine.md) — design of the quote-fairness engine (description + skeleton, deliberately not runnable) | Infrastructure (IaC, deploy, secrets) |
+| [`docs/deck.pdf`](docs/deck.pdf) — the slides from the Demo Day video, appendices included | CRM and installer-partner data |
+
+## The pitch
+
+- **[`docs/deck.pdf`](docs/deck.pdf)** — 15 pages: the twelve slides from
+  the video, plus three appendices that are not spoken in it (why a
+  general-purpose chatbot cannot do this, how the citation gate works, and
+  the push-to-production delivery pipeline).
+- **[`docs/deck.html`](docs/deck.html)** — the same deck, interactive and
+  self-contained: download the raw file and open it in a browser. Arrow
+  keys navigate, `End` jumps to the last spoken slide, and the three
+  appendices follow it.
+
+Both are generated, script-free copies of the presenter deck: the speaker
+notes and the narration are stripped at build time, and
+[`tests/test_published_deck.py`](tests/test_published_deck.py) fails the
+build if a copy still carrying them is ever committed here.
+
+## Install
+
+```bash
+pip install kilowattchiaro-engine
+# or, from source:
+pip install git+https://github.com/domenicodigangi/kilowattchiaro
+```
+
+Python ≥ 3.11. Dependencies: `pydantic`, `pydantic-settings` — nothing else.
+
+## Quickstart
+
+Evaluate a typical Roman household (3,000 kWh/year) putting 6 kWp on the
+roof, with a 10 kWh battery:
+
+```python
+from kilowattchiaro_engine import evaluate_solar
+from kilowattchiaro_engine.models.solar_eval import ConsumptionProfile, PVGISMonthly
+
+consumption = ConsumptionProfile(
+    annual_kwh=3000, f1_kwh=1200, f2_kwh=1050, f3_kwh=750, annual_cost_eur=750.0,
+)
+
+# Monthly production for 6 kWp in Rome (kWh) — normally fetched from PVGIS
+production = [
+    PVGISMonthly(month=m, e_m=e, h_m=h)
+    for m, e, h in [
+        (1, 450, 3.0), (2, 520, 3.5), (3, 720, 4.5), (4, 830, 5.2),
+        (5, 950, 6.0), (6, 1000, 6.5), (7, 1050, 6.8), (8, 980, 6.3),
+        (9, 780, 5.0), (10, 600, 4.0), (11, 420, 3.0), (12, 380, 2.5),
+    ]
+]
+
+result = evaluate_solar(
+    consumption=consumption,
+    monthly_production=production,
+    desired_kwp=6.0,
+    include_battery=True,
+    battery_kwh=10.0,
+)
+
+for s in result.scenarios:
+    print(f"{s.label:22} NPV 20y: {s.npv_20yr_eur or 0:>9,.0f} €   "
+          f"payback: {s.payback_years or float('inf'):>5.1f} y   "
+          f"annual savings: {s.annual_savings_eur:>7,.0f} €")
+```
+
+Every assumption behind those numbers is a named, overridable setting
+(`KWC_ENGINE_*` environment variables — see
+[`src/kilowattchiaro_engine/config.py`](src/kilowattchiaro_engine/config.py))
+and is documented with its value in the
+[assumptions register](docs/methodology.md#12-registro-delle-assunzioni).
+
+## Why deterministic
+
+Large language models do approximate arithmetic; money math shouldn't
+be approximate. In KiloWattChiaro **a model runs in exactly one place**
+— the quote agent that reads unstructured PDFs — and even there, every
+number it states comes from this engine over MCP: same inputs, same
+answer, and anyone can check the logic because the logic is this
+repository.
+
+![Runtime architecture](docs/diagrams/runtime-architecture.svg)
+
+The second invariant is drawn in the diagram: the engines that judge
+your roof and your quote don't know the installers exist. The booking
+service is a separate system with no AI in it; the only thing that
+crosses the separation is the homeowner's own click. The check cannot
+favor the sale.
+
+More in [`docs/architecture.md`](docs/architecture.md) — including the
+delivery pipeline (tests and an eval gate on every change, among them a
+fault-injection eval that fails the build if a fabricated datasheet is
+ever cited).
+
+## Tests
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+325 tests across the engine: unit tests for every module (tariff
+classification, load-profile inference, hourly matching, price
+projections, incentive regimes, household estimation), numerical stress
+tests (zero/near-zero edge cases), validation against reference
+outcomes, and historical backtests replaying every Italian incentive
+regime from 2011 to 2025.
+
+## Related
+
+- **[kilowattchiaro.it](https://kilowattchiaro.it)** — the live product:
+  solar evaluation (free, no account), quote check and booking (free, a
+  sign-up).
+- **[Quote check](https://kilowattchiaro.it/preventivo)** — the agentic
+  quote reviewer in production (LangGraph, MCP, Qdrant, citation-gated
+  RAG, eval harness).
+- **[Open data](https://kilowattchiaro.it/open-data)** — datasets under
+  CC BY 4.0, including the photovoltaic price rubric.
+
+## License
+
+**Source-available** — read, run, and verify freely; commercial use or
+redistribution requires written permission. See [LICENSE.md](LICENSE.md).
+This is a published package, deliberately not open source: transparency
+is the point, the product is the business.
+
+## Author
+
+**Domenico Di Gangi** — solo founder, Pisa, Italy. KiloWattChiaro is
+built and operated end-to-end by one person: product, engine, agent,
+infrastructure.
+
+Contact: **kilowattchiaro@gmail.com**

kilowattchiaro_engine-0.1.0/README.md

@@ -0,0 +1,166 @@
+# KiloWattChiaro
+
+> **The independent check on the solar purchase.**
+> Live and free at **[kilowattchiaro.it](https://kilowattchiaro.it)**.
+
+[![ci](https://github.com/domenicodigangi/kilowattchiaro/actions/workflows/ci.yml/badge.svg)](https://github.com/domenicodigangi/kilowattchiaro/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kilowattchiaro-engine)](https://pypi.org/project/kilowattchiaro-engine/)
+[![License: Source-Available](https://img.shields.io/badge/license-source--available-8a6d1a)](LICENSE.md)
+
+An Italian homeowner considering rooftop solar has two questions nobody
+neutral will answer: **is solar worth it for my house?** and **is this
+quote fair?** The market's default path runs through lead aggregators
+that resell your phone number to competing installers — everyone you can
+ask gets paid if you say yes.
+
+KiloWattChiaro is the neutral answer: a **deterministic evaluation
+engine** with a fully published methodology, an **agentic quote
+reviewer** that must back every technical claim with a manufacturer
+datasheet citation, and a hard architectural wall between the check and
+the sale — a *"solar is not worth it for your roof"* verdict is a
+first-class result, presented exactly like a yes.
+
+## What's in this repository
+
+This repo publishes the part of the product whose entire value is being
+inspectable — the code that computes every number a homeowner sees:
+
+| Public — this repo | Private — the product |
+|---|---|
+| `src/kilowattchiaro_engine/` — the deterministic evaluation engine, **exactly as deployed in production** (NPV, IRR, payback, hourly self-consumption, price scenarios, historical backtests) | Web app, HTTP service layer, persistence |
+| `tests/` — 325 tests: unit, stress, validation, and backtests across the 2011–2025 Italian incentive regimes | Booking service (separate system, no AI in it) |
+| [`docs/methodology.md`](docs/methodology.md) — the full methodology: every formula and every assumption, with values | Quote-agent runtime — in production at [kilowattchiaro.it/preventivo](https://kilowattchiaro.it/preventivo) |
+| [`docs/architecture.md`](docs/architecture.md) — system design, runtime + delivery diagrams | Component catalogue & price-benchmark data ([open rubric CSV](https://kilowattchiaro.it/open-data) is CC BY 4.0) |
+| [`docs/quote-engine.md`](docs/quote-engine.md) — design of the quote-fairness engine (description + skeleton, deliberately not runnable) | Infrastructure (IaC, deploy, secrets) |
+| [`docs/deck.pdf`](docs/deck.pdf) — the slides from the Demo Day video, appendices included | CRM and installer-partner data |
+
+## The pitch
+
+- **[`docs/deck.pdf`](docs/deck.pdf)** — 15 pages: the twelve slides from
+  the video, plus three appendices that are not spoken in it (why a
+  general-purpose chatbot cannot do this, how the citation gate works, and
+  the push-to-production delivery pipeline).
+- **[`docs/deck.html`](docs/deck.html)** — the same deck, interactive and
+  self-contained: download the raw file and open it in a browser. Arrow
+  keys navigate, `End` jumps to the last spoken slide, and the three
+  appendices follow it.
+
+Both are generated, script-free copies of the presenter deck: the speaker
+notes and the narration are stripped at build time, and
+[`tests/test_published_deck.py`](tests/test_published_deck.py) fails the
+build if a copy still carrying them is ever committed here.
+
+## Install
+
+```bash
+pip install kilowattchiaro-engine
+# or, from source:
+pip install git+https://github.com/domenicodigangi/kilowattchiaro
+```
+
+Python ≥ 3.11. Dependencies: `pydantic`, `pydantic-settings` — nothing else.
+
+## Quickstart
+
+Evaluate a typical Roman household (3,000 kWh/year) putting 6 kWp on the
+roof, with a 10 kWh battery:
+
+```python
+from kilowattchiaro_engine import evaluate_solar
+from kilowattchiaro_engine.models.solar_eval import ConsumptionProfile, PVGISMonthly
+
+consumption = ConsumptionProfile(
+    annual_kwh=3000, f1_kwh=1200, f2_kwh=1050, f3_kwh=750, annual_cost_eur=750.0,
+)
+
+# Monthly production for 6 kWp in Rome (kWh) — normally fetched from PVGIS
+production = [
+    PVGISMonthly(month=m, e_m=e, h_m=h)
+    for m, e, h in [
+        (1, 450, 3.0), (2, 520, 3.5), (3, 720, 4.5), (4, 830, 5.2),
+        (5, 950, 6.0), (6, 1000, 6.5), (7, 1050, 6.8), (8, 980, 6.3),
+        (9, 780, 5.0), (10, 600, 4.0), (11, 420, 3.0), (12, 380, 2.5),
+    ]
+]
+
+result = evaluate_solar(
+    consumption=consumption,
+    monthly_production=production,
+    desired_kwp=6.0,
+    include_battery=True,
+    battery_kwh=10.0,
+)
+
+for s in result.scenarios:
+    print(f"{s.label:22} NPV 20y: {s.npv_20yr_eur or 0:>9,.0f} €   "
+          f"payback: {s.payback_years or float('inf'):>5.1f} y   "
+          f"annual savings: {s.annual_savings_eur:>7,.0f} €")
+```
+
+Every assumption behind those numbers is a named, overridable setting
+(`KWC_ENGINE_*` environment variables — see
+[`src/kilowattchiaro_engine/config.py`](src/kilowattchiaro_engine/config.py))
+and is documented with its value in the
+[assumptions register](docs/methodology.md#12-registro-delle-assunzioni).
+
+## Why deterministic
+
+Large language models do approximate arithmetic; money math shouldn't
+be approximate. In KiloWattChiaro **a model runs in exactly one place**
+— the quote agent that reads unstructured PDFs — and even there, every
+number it states comes from this engine over MCP: same inputs, same
+answer, and anyone can check the logic because the logic is this
+repository.
+
+![Runtime architecture](docs/diagrams/runtime-architecture.svg)
+
+The second invariant is drawn in the diagram: the engines that judge
+your roof and your quote don't know the installers exist. The booking
+service is a separate system with no AI in it; the only thing that
+crosses the separation is the homeowner's own click. The check cannot
+favor the sale.
+
+More in [`docs/architecture.md`](docs/architecture.md) — including the
+delivery pipeline (tests and an eval gate on every change, among them a
+fault-injection eval that fails the build if a fabricated datasheet is
+ever cited).
+
+## Tests
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+325 tests across the engine: unit tests for every module (tariff
+classification, load-profile inference, hourly matching, price
+projections, incentive regimes, household estimation), numerical stress
+tests (zero/near-zero edge cases), validation against reference
+outcomes, and historical backtests replaying every Italian incentive
+regime from 2011 to 2025.
+
+## Related
+
+- **[kilowattchiaro.it](https://kilowattchiaro.it)** — the live product:
+  solar evaluation (free, no account), quote check and booking (free, a
+  sign-up).
+- **[Quote check](https://kilowattchiaro.it/preventivo)** — the agentic
+  quote reviewer in production (LangGraph, MCP, Qdrant, citation-gated
+  RAG, eval harness).
+- **[Open data](https://kilowattchiaro.it/open-data)** — datasets under
+  CC BY 4.0, including the photovoltaic price rubric.
+
+## License
+
+**Source-available** — read, run, and verify freely; commercial use or
+redistribution requires written permission. See [LICENSE.md](LICENSE.md).
+This is a published package, deliberately not open source: transparency
+is the point, the product is the business.
+
+## Author
+
+**Domenico Di Gangi** — solo founder, Pisa, Italy. KiloWattChiaro is
+built and operated end-to-end by one person: product, engine, agent,
+infrastructure.
+
+Contact: **kilowattchiaro@gmail.com**

kilowattchiaro_engine-0.1.0/docs/architecture.md

@@ -0,0 +1,79 @@
+# Architecture
+
+How KiloWattChiaro runs in production, and how changes reach it. The two
+diagrams below are the same ones used in the demo-day deck; every fact on
+them is current as of August 2026.
+
+## Runtime — one VPS, one agent, one wall
+
+![Runtime architecture](diagrams/runtime-architecture.svg)
+
+**The main box is a single European VPS** (Hetzner, Falkenstein), fronted
+by Cloudflare and routed internally by Traefik, running three containers
+under Docker Compose:
+
+- **Next.js 14** (`:3000`) — the web app at
+  [kilowattchiaro.it](https://kilowattchiaro.it).
+- **Solar API — FastAPI** (`:8000`) — the service layer around the
+  [deterministic engine published in this repository](../src/kilowattchiaro_engine/).
+  It also exposes an **MCP server** at `/api/mcp` (`solar_evaluate_v2`,
+  `quote_compare_v1`), so agents can call the engine as a tool instead of
+  doing arithmetic themselves.
+- **Booking — FastAPI** (`:8010`) — a deliberately separate service with
+  **no LLM in it** and its own store (SQLite CRM). It verifies user
+  identity against Supabase read-only and never touches the evaluation
+  database.
+
+**The quote agent** runs elsewhere on purpose — Fly.io Frankfurt
+(`:7860`): OCR → strict structured extraction, component resolution
+against a curated, datasheet-pinned catalogue (1,885 SKUs), Qdrant
+retrieval over ~4,900 indexed datasheet chunks, a web-hunt fallback for
+unknown components, and Redis for daily quotas and a short document
+cache. Quote PDFs upload **directly from the browser to Fly** under a
+five-minute HMAC grant — pseudonymous: Fly never receives the Supabase
+identity, and the browser never sees the service credential.
+
+**Supabase** (Frankfurt, AWS eu-central-1) holds Postgres and auth —
+user profiles and evaluations.
+
+### The two invariants the diagram encodes
+
+1. **The model runs in exactly one box.** The quote agent is the only
+   place an LLM executes, and every number it states comes from the
+   deterministic engine over MCP — same inputs, same answer. The engine
+   itself has no model in it (you can read all of it in this repo).
+2. **The check cannot favor the sale.** The engines that judge a roof or
+   a quote don't know the installers exist. The booking service is a
+   separate system; the only thing that crosses the separation is the
+   homeowner's explicit click, carrying their evaluation to the one
+   installer they named. A negative verdict is a full result.
+
+## Delivery — from push to production
+
+![Delivery pipeline](diagrams/delivery-pipeline.svg)
+
+Every push runs CI: 650+ tests across backend, frontend, agent, and E2E,
+plus an **eval gate** on the agent (SKU-resolution and web-evidence
+admission benchmarks; a fault-injection suite feeds the agent fabricated
+datasheets and fails the build if fabricated content is ever cited).
+Green CI auto-deploys to a **test environment reachable only over
+Tailscale**, where a three-stage QA gate runs before a release candidate
+is tagged. Production is a **manual promotion** of a tagged RC, followed
+by an automatic smoke gate on the live URLs. Infrastructure is OpenTofu;
+secrets are SOPS-encrypted in-repo.
+
+## Where this repository fits
+
+```
+public                                   private
+──────────────────────────────────────   ─────────────────────────────────
+this repo                                watt-chiaro monorepo
+  kilowattchiaro-engine (the math)   ◄── service layer imports the engine
+  methodology, diagrams, docs            web app · booking · agent runtime
+                                         catalogue data · infra · deploy
+kilowattchiaro-agent (source snapshot)◄─ agent/ subtree, minus data
+```
+
+The engine package is the exact code in production; the private service
+layer contributes only I/O — HTTP connectors (PVGIS, Google Solar),
+persistence, auth, and orchestration.