Metadata-Version: 2.4
Name: solystopia-hearthmind-economics
Version: 0.1.0
Summary: Four transparent, formula-based calculators for planning household AI infrastructure. Part of the Solystopia open-source toolkit.
Author-email: Arthur Silas <arthur-silas@agentmail.to>
License: MIT
Project-URL: Homepage, https://github.com/arthursilas-ai/hearthmind-economics
Project-URL: Repository, https://github.com/arthursilas-ai/hearthmind-economics
Keywords: solystopia,python,cli,calculator,renewable-energy,sovereign-compute,off-grid
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hearthmind-economics

Four transparent, formula-based calculators for planning household AI infrastructure.

Extracted from [Project Hearthmind](https://solystopia.tech/hearthmind/tools) — the Solystopia experiment in sovereign household compute.

No model calls. No internet required after install. No account. Pure Python.

---

## Calculators

| Command | What it calculates |
|---|---|
| `tco` | Local hardware vs cloud equivalent — annual cost, break-even, 5-year totals |
| `renewable` | Solar + battery ROI against displaced grid electricity |
| `heat` | Waste heat recovery value — compute heat captured during heating season |
| `container` | Compute container sizing — kW load, floor area, annual electricity cost |

Run one or all four interactively. Every assumption is prompted, every formula is documented in the source.

---

## Install

No dependencies beyond Python 3.9+. No repo to clone required — pick one:

```bash
# As a CLI, straight from GitHub (no PyPI account needed)
pip install git+https://github.com/arthursilas-ai/hearthmind-economics.git
hearthmind-economics all

# As an agent skill (Claude Code, Cursor, Copilot, and others)
npx skills add arthursilas-ai/hearthmind-economics

# Or standalone — one file, no install
curl -O https://raw.githubusercontent.com/arthursilas-ai/hearthmind-economics/main/hearthmind_economics.py
python hearthmind_economics.py all
```

---

## Usage

```bash
# Interactive — prompts for inputs, shows results
python hearthmind_economics.py tco
python hearthmind_economics.py renewable
python hearthmind_economics.py heat
python hearthmind_economics.py container
python hearthmind_economics.py all        # run all four

# Machine-readable output
python hearthmind_economics.py tco --json
python hearthmind_economics.py all --json
```

### Example: TCO run

```
  LOCAL VS CLOUD — Total Cost of Ownership
  Straight-line depreciation. No resale, no financing, no inflation.

  Capital cost [£] (default 4500): 4699
  Useful life [years] (default 5): 5
  Annual electricity cost [£/yr] (default 300): 320
  Annual maintenance [£/yr] (default 100): 80
  Equivalent cloud spend [£/month] (default 90): 110

  ────────────────────────────────────────────────────────────
  Local annual cost   £1,340
  Cloud annual cost   £1,320
  Break-even          4.8 years
  5-year local total  £6,699
  5-year cloud total  £6,600
  ────────────────────────────────────────────────────────────
  → local hardware breaks even in 4.8 years — profitable over 5-year life
```

---

## The formulas

All formulas are documented in the source. The short versions:

**TCO**
```
annual_depreciation = capital_cost / useful_life       # straight-line
local_annual = depreciation + electricity + maintenance
cloud_annual = cloud_monthly * 12
break_even = capital_cost / (cloud_annual - electricity - maintenance)
```

**Renewable ROI**
```
annual_saving = kwh_displaced * grid_price
payback = (solar + battery) / annual_saving
lifetime_saving = (annual_saving * system_life) - (solar + battery)
```

**Waste heat**
```
recoverable_kwh = (watts / 1000) * hours_per_day * season_days * efficiency
annual_value = recoverable_kwh * heat_price
```

**Container sizing**
```
total_kw = (unit_count * unit_watts) / 1000
total_kw_with_overhead = total_kw * PUE
floor_area_m2 = total_kw_with_overhead * m2_per_kw
annual_kwh = total_kw_with_overhead * active_hours
```

---

## What this doesn't model

**TCO:** resale value, financing cost, inflation, insurance.

**Renewable ROI:** feed-in tariff, panel degradation over time, battery replacement cost, regional irradiance variation, shading.

**Waste heat:** no heat-recovery hardware has been built or tested for Project Hearthmind yet — these are planning estimates.

**Container:** generator overhead, cooling redundancy, fit-out cost, planning permission.

These are planning tools, not financial guarantees.

---

## Context

This tool is part of the [Solystopia](https://solystopia.tech) open-source ecosystem — a set of tools for people who want to bring AI capability back to the household level.

The calculators were built to support Project Hearthmind, an experiment in acquiring sovereign household AI infrastructure. The live interactive versions are at [solystopia.tech/hearthmind/tools](https://solystopia.tech/hearthmind/tools).

Other tools in the ecosystem:
- [agent-preflight](https://github.com/arthursilas-ai/agent-preflight) — pre-deployment checks for AI agents
- [piper-local-tts-demo](https://github.com/arthursilas-ai/piper-local-tts-demo) — local text-to-speech
- [household-capability-audit](https://github.com/arthursilas-ai/household-capability-audit) — dependency mapping questionnaire
- [sovereign-ai-harness](https://github.com/arthursilas-ai/sovereign-ai-harness) — 10-stage local AI setup guide

---

## License

MIT. Use it, modify it, ship it.
