Metadata-Version: 2.4
Name: asi-proxy-phase-growth-simulator
Version: 0.1.0
Summary: Python Monte Carlo simulator for uncertainty, risk, verification, and resource-constrained scenario analysis.
Project-URL: Homepage, https://github.com/kadubon/asi-proxy-phase-growth-simulator
Project-URL: Repository, https://github.com/kadubon/asi-proxy-phase-growth-simulator
Project-URL: Documentation, https://github.com/kadubon/asi-proxy-phase-growth-simulator/tree/main/docs
Project-URL: Issues, https://github.com/kadubon/asi-proxy-phase-growth-simulator/issues
Project-URL: Changelog, https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/main/CHANGELOG.md
Author: ASI-Proxy Phase Growth Simulator contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: monte-carlo,risk-analysis,scenario-analysis,scientific-computing,simulation,streamlit,uncertainty-quantification,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.12
Requires-Dist: jsonschema>=4.23
Requires-Dist: numpy>=2.1
Requires-Dist: pandas>=2.2
Requires-Dist: plotly>=5.24
Requires-Dist: pydantic>=2.10
Requires-Dist: scipy>=1.14
Requires-Dist: streamlit>=1.41
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: bandit>=1.8; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hypothesis>=6.120; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# ASI-Proxy Phase Growth Simulator

**A Python research simulator for Monte Carlo scenario analysis, uncertainty quantification,
sensitivity analysis, and interactive risk modeling under verification, provenance, memory,
coordination, debt, hazard, and finite-resource constraints.**

> This project does **not** predict ASI, estimate when superintelligence will appear, or certify
> that any system is ASI. It models a protocol-relative operational proxy in synthetic scenarios.

[![Python 3.12–3.13](https://img.shields.io/badge/Python-3.12%20%7C%203.13-blue)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/asi-proxy-phase-growth-simulator)](https://pypi.org/project/asi-proxy-phase-growth-simulator/)
[![CI](https://github.com/kadubon/asi-proxy-phase-growth-simulator/actions/workflows/ci.yml/badge.svg)](https://github.com/kadubon/asi-proxy-phase-growth-simulator/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green)](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/LICENSE)
[![Status: alpha](https://img.shields.io/badge/status-research%20alpha-orange)](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/CHANGELOG.md)

![Streamlit Growth Dashboard comparing the baseline with a selected scenario](https://raw.githubusercontent.com/kadubon/asi-proxy-phase-growth-simulator/v0.1.0/docs/assets/growth-dashboard.png)

## Start here

The simulator treats agent output as candidate work, not as capability capital. Candidate work
must pass limited verification, independent-trust, provenance, temporal-validity, causal-support,
and reuse gates. Unresolved work becomes visible residual debt. Capital also consumes resources
and can decay through evidence expiry, memory staleness, monoculture, and incidents.

This makes the tool useful for questions such as:

- What happens with no OSS intervention?
- Does verification keep pace with candidate generation?
- Which readiness dimension is binding?
- Do intervention benefits survive their implementation and operating costs?
- Which module has the largest marginal contribution inside the model after overlap correction?
- Does a candidate regime survive expiry, monoculture, memory, coordination, or resource shocks?

Every answer is conditional on the scenario and model structure. It is not a world forecast.

Common use cases include scientific computing, research software validation, resource-constrained
growth simulation, open-source intervention analysis, reproducible experiments, and interactive
Streamlit dashboards.

## Install from PyPI

Python 3.12 or 3.13 and [`uv`](https://docs.astral.sh/uv/) are recommended:

```powershell
uv tool install asi-proxy-phase-growth-simulator
apxsim doctor
apxsim gui
```

To run a one-off command without a persistent installation:

```powershell
uvx --from asi-proxy-phase-growth-simulator apxsim doctor
```

## Install from source

Python 3.12 or 3.13 is required. `uv` is the sole supported environment manager.

```powershell
git clone https://github.com/kadubon/asi-proxy-phase-growth-simulator.git
cd asi-proxy-phase-growth-simulator
uv sync --frozen --all-extras --group dev
```

During local development, omit `--frozen` only when intentionally updating `uv.lock`:

```powershell
uv sync --all-extras --group dev
```

No `requirements.txt`, database, cloud SDK, LLM API, secret, or external service is required.

## Launch the Streamlit interface

```powershell
uv run streamlit run streamlit_app.py
```

or:

```powershell
uv run apxsim gui
```

The interface has nine tabs:

1. Overview
2. Scenario Builder
3. Growth Dashboard
4. Phase Diagnostics
5. OSS Contributions
6. Monte Carlo & Sensitivity
7. Evidence Import
8. Export & Reproducibility
9. About & Limitations

All major controls show plain-language labels, technical names, ranges, units, directions, and
assumption warnings. The app performs local computation, has no telemetry, and limits JSON
uploads to 1 MB in memory.

## Command-line examples

```powershell
uv run apxsim run --preset baseline --out outputs/baseline
uv run apxsim run --scenario scenario.json --out outputs/custom
uv run apxsim compare --baseline baseline.json --candidate candidate.json
uv run apxsim monte-carlo --scenario scenario.json --runs 300 --seed 42
uv run apxsim ablate --scenario scenario.json
uv run apxsim sensitivity --scenario scenario.json
uv run apxsim validate --preset baseline
uv run apxsim catalog list
uv run apxsim catalog validate
uv run apxsim evidence validate evidence.json
uv run apxsim report outputs/custom/result.json --out report.md
uv run apxsim doctor
```

Each command accepts `--json` and `--deterministic/--stochastic`. Commands return non-zero exit
codes for invalid inputs or failed validation.

## Model in plain language

The main state contains:

- gross certified reusable capability capital;
- problem-frame quality;
- availability bandwidth;
- coordination integrity;
- verification capacity;
- effective verifier independence;
- provenance integrity;
- certified-memory retention;
- temporal integrity;
- causal support;
- residual debt;
- hazard pressure; and
- a finite resource stock.

Candidate generation is resource-saturated and depends on capital, framing, availability,
coordination, and certified memory:

```text
Q = q0 × B/(B + κB) × (1 + λK log(1 + K)) × F^aF × W^aW × C^aC × M^aM
```

Verification coverage is verification throughput divided by candidate flow, capped at one.
Verified yield also depends on independence, provenance, temporal validity, causal support, and
hazard pressure. Only verified, reusable yield enters capital. Unknown and rejected work enters
residual debt rather than disappearing.

Euler and RK4 are available as reproducible fixed-step integrators. RK4 is the default. The CLI
validation command compares `dt` with `dt/2` as a convergence check.

See [Model reference](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/model-reference.md) for equations, units, update order, and boundary
handling.

## Main vertical quantity

```text
A(t) = K(t) × Φ(t)
```

- `A`: Protocol-relative ASI-Proxy Capital.
- `K`: gross certified reusable capability capital.
- `Φ`: phase readiness after a bottleneck-sensitive 13-dimensional profile and residual penalty.

The 13 dimensions are inspired by the Collective Phase Control Fabric concepts but are an
operational mapping inside this simulator—not CPCF scientific certification. The default
generalized mean uses `p = -4`, so a weak dimension constrains the total more strongly than it
would under an arithmetic mean. The arithmetic mean is shown only for comparison.

The capability reproduction number is:

```text
R_cap = certified inflow / (natural decay + verifier-monoculture loss + epsilon)
```

`R_cap > 1` means inflow exceeds losses inside the current model. It is not sufficient for the
candidate regime and is never interpreted as ASI attainment.

## Candidate regime gate

The label `candidate ASI-proxy growth regime` appears only after all of the following hold for a
configured duration:

- phase readiness reaches its threshold;
- `R_cap > 1`;
- residual debt relative to capital remains below its threshold;
- verification coverage reaches its threshold;
- resources remain above their floor;
- no critical unknown is unresolved; and
- the conditions persist for `hold_steps`.

The label is an operational scenario result, not a scientific proof of a phase transition.

## OSS intervention catalog

The catalog contains semantic mappings for:

| ID | Module | Primary modeled role |
|---|---|---|
| `pic` | Percolation Inversion Compiler | verification, residual repair, safe reuse |
| `ccr` | Collective Capability Runtime | coordination, recovery, independence |
| `cpcf` | Collective Phase Control Fabric | diagnostics, gates, unknown preservation |
| `alt_foundry` | ALT Foundry Kernel | reusable certified abstraction capital |
| `cgt_bandwidth` | CGT Bandwidth Dynamics | constraint bandwidth and continuation |
| `cgt_availability` | CGT Availability | deficiency and comparison readiness |
| `problem_frame_gate` | Problem Frame Gate | problem framing and waste/risk routing |
| `verification_ecology` | Verification Ecology Kit | verifier diversity and counter-checks |
| `fost_ledger` | FOST Agent Ledger | provenance and unresolved obligations |
| `future_claim_certifier` | Future Claim Certifier | expiry and temporal authority |
| `observable_workflow_memory` | Observable Agent Workflow Memory | evidence-bound procedural reuse |
| `memoryflow_auditor` | MemoryFlow Agent Memory Auditor | memory contamination auditing |
| `certified_memory_governance` | Certified Memory Governance Layer | revocation and retention governance |
| `atrb_calibration` | Agent Trust and Residual Benchmark | system-level calibration only |

Effects are conservative `theory_mapped_assumption` synthetic priors. Modules in the same overlap
group use the maximum effect, not a sum. Different groups use a bounded union. Synergy is zero
unless explicitly specified. All modules have implementation and operating costs.

ATRB conditions are cumulative. Intermediate condition differences are never converted into
individual module effects.

See [OSS mapping](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/oss-mapping.md) and [reference audit](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/reference-audit.md).

## Scenario presets

- Baseline
- Trust and Verification Foundation
- Collective Runtime Stack
- Reusable Capital Stack
- Full Conservative Stack
- Fast Candidates / Weak Verification
- Verifier Monoculture Shock
- Evidence Expiry Shock
- Memory Poisoning Shock
- Resource-Constrained Full Stack

Every preset is synthetic and normalized. None is a forecast.

## Unknowns and uncertainty

Typed inputs distinguish `KnownScalar`, `ProbabilityDistribution`, `BoundedInterval`, and
`UnknownValue`. Unknowns are not silently converted to zero, a midpoint, or a safe-looking value.
The default policy is no imputation. A bounded unknown may be sampled only when the user explicitly
chooses the `sample` policy; outputs are then labelled `imputed`.

Seeded Monte Carlo uses NumPy `Generator` and reports median, p10–p90, p2.5–p97.5, final
distributions, threshold-time distribution, no-transition fraction, resource exhaustion, failed
runs, and an operational false-promotion incident indicator. These bands represent uncertainty
inside the model, not total real-world uncertainty.

Sensitivity tools include one-at-a-time tornado data, Spearman rank correlation, leave-one-module-
out ablation, and seeded approximate Shapley attribution for at most 12 modules.

## Evidence import and calibration

The project follows:

```text
semantic integration first
artifact adapter second
hard runtime dependency last
```

PIC, ATRB, and generic-status adapters normalize JSON without importing source OSS packages.
Missing and incompatible fields remain unknown. Calibration rejects expired, out-of-scope, or
non-causally-identified observations for module-specific effect updates. Non-resource-matched
comparisons receive lower weight. The documented optional update is transparent inverse-variance
shrinkage; prior and posterior are both retained.

## Exports

Each run can export:

- scenario JSON;
- result JSON;
- flat result CSV;
- metrics JSON;
- Markdown report;
- provenance manifest; and
- SHA-256 digest manifest.

Exports record software version, seed, selected modules, assumptions, event order, and unresolved
unknowns. A safety scan rejects common absolute local paths and secret-assignment patterns.

## Testing and quality checks

```powershell
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest --cov=asi_proxy_sim --cov-fail-under=90
uv run bandit -r src
uv run pip-audit
uv run python -m compileall -q src
uv run apxsim catalog validate
uv run apxsim validate --preset baseline
uv build
uv run twine check dist/*
```

The suite covers bounds, reproducibility, no-module effects, zero adoption, unknown preservation,
resource matching, overlap, synergy defaults, phase monotonicity, debt penalty, inflow limits,
convergence, shocks, Monte Carlo, adapters, CLI, and Streamlit import/render smoke tests. Coverage
configuration and justified exclusions are documented in [Validation](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/validation.md).

## Streamlit Community Cloud configuration

This repository is prepared for, but not deployed to, Streamlit Community Cloud. Use:

- Repository: `asi-proxy-phase-growth-simulator`
- Branch: `main`
- Main file: `streamlit_app.py`
- Python: `3.12`

The canonical environment is `pyproject.toml` plus `uv.lock`. Do not add a competing
`requirements.txt` unless deployment testing proves it necessary and its generation source is
documented. Public hosting should occur only after the human checks below.

## Human checks before public release

1. Confirm repository links, maintainer attribution, and private vulnerability-reporting access.
2. Have a domain reviewer examine every synthetic coefficient, operational threshold, non-claim,
   and source mapping; record disagreements rather than presenting consensus that does not exist.
3. Confirm that the dashboard screenshot was generated from a reviewed, non-sensitive scenario and
   does not expose local paths or private data.
4. Re-run the full quality commands on the exact release commit and inspect the built wheel and
   source archive; verify that no credentials, private inputs, absolute paths, or generated outputs
   are present.
5. Before any public hosting, review the host's current terms, logging/privacy behavior, Python and
   resource limits, dependency installation path, and abuse controls. Do not upload secrets or
   confidential evidence.

## Scientific limits

- This is not an ASI forecast, probability model, or certification system.
- It does not perform real-world causal inference.
- Most effect priors are assumptions, not measurements.
- Repository quality, stars, commits, and lines of code are not effect sizes.
- Cross-module interactions are incompletely identified.
- Phase thresholds are operational choices.
- Prediction bands are model-internal uncertainty bands.
- Structural uncertainty is only partly represented.
- Not every social, physical, or economic constraint is included.
- Implemented software does not guarantee successful adoption or benefit.

Read [Limitations](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/limitations.md) before interpreting results.

## Security and privacy

There are no external API calls, telemetry, analytics, secrets, arbitrary code execution, pickle
uploads, or unsafe YAML loaders. Uploaded scenario/evidence JSON is size-limited, decoded in
memory, and schema-validated. See [SECURITY.md](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/SECURITY.md) for the threat model.

## Documentation

- [Japanese guide / 日本語ガイド](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/README_ja.md)
- [Model reference](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/model-reference.md)
- [Theory mapping](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/theory-mapping.md)
- [OSS mapping](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/oss-mapping.md)
- [Assumptions](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/assumptions.md)
- [Validation](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/validation.md)
- [Uncertainty](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/uncertainty.md)
- [GUI guide](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/gui-guide.md)
- [CLI guide](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/cli-guide.md)
- [Developer guide](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/developer-guide.md)
- [Limitations](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/limitations.md)
- [Security notes](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/docs/security.md)

## License and citation

Licensed under Apache-2.0. See [LICENSE](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/LICENSE) and [NOTICE](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/NOTICE).

Citation metadata is provided in [CITATION.cff](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/CITATION.cff) and [codemeta.json](https://github.com/kadubon/asi-proxy-phase-growth-simulator/blob/v0.1.0/codemeta.json).
Until a public archive DOI exists, cite the versioned repository and commit used. Do not invent a
DOI or imply external scientific validation.
