Axiomize

Axiomize

現実に直面しても再現可能な科学モデリング。 Axiomize はあいまいなアイデアを明示的でバージョン管理された数学モデルに変換し、次元と数値の両面から検証して、何年後でも他の人が再実行できる成果物としてエクスポートします。

これは数値計算ライブラリではありません。その役割はscientific-computing-systemが担います。Axiomize はモデリング層です。必須の単位、バージョン管理された Model IR、SBML、CellML、Modelica へのエクスポートを提供します。MCP サーバーは axiomize mcp です。

mcp-name: io.github.Furox-Art/axiomize

現在のパッケージ系列：1.14.2。PyPI では 1.14.2、npm では 1.14.1 が提供されています。レジストリごとの提供状況は docs/documentation.mdで追跡されています。上記のバッジはリアルタイムで更新され、正確な情報を示します。

ドキュメント：furox-art.github.io/axiomize · 変更履歴：CHANGELOG.md · ロードマップ：ROADMAP.md · セキュリティ：SECURITY.md · 貢献方法：CONTRIBUTING.md · 行動規範：CODE_OF_CONDUCT.md · 引用：CITATION.cff

理由

Jupyter ノートブックに残され、その中で使えなくなる科学モデルにうんざりしていました。

誰かが見事なシミュレーションを書き、自分のマシンでは動きますが、卒業したり転職したりすると、半年後には誰も実行できなくなります。依存関係は壊れ、データは失われ、「ドキュメント」は説明のない47セルのノートブックです。

Axiomize は、モデルを探索的なスパゲッティコードではなく、明示的でバージョン管理され、テスト可能なコードにすることを徹底します。すべての仮定が書き留められます。すべてのパラメーターに単位が付与されます。すべての結果には、別のマシンを使う別の人が再現できるだけの来歴情報が含まれます。

対象ユーザー

こんな方に…	こちらから始めてください
査読で結果を裏付ける必要がある科学者	理由とサンプルギャラリー
容量、信頼性、在庫を算定するエンジニア	CLI クイックスタートとaxiomize solve／axiomize fit
感覚ではなく数値に基づいて推論するエージェントを構築する方	axiomize capabilitiesを実行し、MCP または RESTを参照
他の人が公開したモデルを再現または監査する方	axiomize model --action numerical-verifyと移植可能なエクスポート

対象外：仮定を確認できないブラックボックス予測器を求めている場合や、人間が関与せずにエンジンが科学的な主張を行う必要がある場合には適していません。

インストール

pip install axiomize

オプションの追加機能：ベイズサンプリング用の PyMC／JAX を使うには、pip install "axiomize[full]"を実行します。

playground追加機能はgradioとpandasをインストールしますが、UI は含まれません。playground/app.pyは wheel にも sdist にも含まれないため、pip install "axiomize[playground]"だけでは依存関係がインストールされるだけで、実行できるものはありません。使用するには、リポジトリからファイルを取得してください。

git clone https://github.com/Furox-Art/axiomize
pip install "axiomize[playground]"
python axiomize/playground/app.py

5分でわかるPython

モデルを宣言し、Axiomize にチェックさせます。単位は必須のため、次元の誤りは無意味な数値を出すのではなく、明確なエラーになります。このブロックは、examples/quickstart_sir.py にあるモデルをフィールドごとに示したものです。

from axiomize.general_engine import simulate_model
from axiomize.model_ir import ModelIR

model = ModelIR.from_dict({
    "schema_version": "1.0",
    "name": "sir-outbreak",
    "domain": "epidemiology",
    "family": "ode",
    "independent_variable": "t",
    "independent_unit": "day",
    "variables": [
        {"name": "S", "unit": "person", "initial": 990.0, "bounds": [0.0, None]},
        {"name": "I", "unit": "person", "initial": 10.0, "bounds": [0.0, None]},
    ],
    "parameters": [
        {"name": "beta", "unit": "1/day", "value": 0.3, "bounds": [0.0, None]},
        {"name": "gamma", "unit": "1/day", "value": 0.1, "bounds": [0.0, None]},
        {"name": "N", "unit": "persons", "value": 1000.0},
    ],
    "equations": [
        {"target": "S", "expression": "-beta*I*S/N", "kind": "derivative"},
        {"target": "I", "expression": "beta*I*S/N - gamma*I", "kind": "derivative"},
    ],
    "constraints": [
        {"name": "cases_nonnegative", "expression": "I", "relation": "ge",
         "threshold": 0.0, "scientific_basis": "case counts cannot be negative"},
    ],
    "assumptions": ["closed population of 1000", "homogeneous mixing"],
})

result = simulate_model(model, t_span=(0.0, 30.0), points=4)
print(f"status: {result['status']}")
print(f"solver: {result['solver']['backend']} / {result['solver']['method']}")
print(f"days:   {result['time']}")
print(f"infected: {[round(v, 3) for v in result['states']['I']]}")
print(f"checks: {result['validation']['status']} ({len(result['validation']['checks'])} of them)")

実際の出力です。python examples/quickstart_sir.py の出力とバイト単位で一致します。

status: PASS
solver: scipy / DOP853
days:   [0.0, 10.0, 20.0, 30.0]
infected: [10.0, 65.393, 239.869, 290.024]
checks: PASS (25 of them)

5分でわかるCLI

すべてのコマンドは、パイプで渡せる JSON を出力します。

# What is actually installed, and is it usable? Backends report honestly.
axiomize capabilities

# Clarify a vague idea before any numbers get committed.
axiomize intake "Reduce traffic congestion in a mid-size city"

# Check a model against closed-form theory, not just vibes.
axiomize-validate --model sir --beta 0.3 --gamma 0.1

これらの入力に対する axiomize-validate の出力です。

=== SIR validation ===
horizon                = 180 days  (final-size theory is the t->infinity limit)
R0                     = 3.000  (outbreak)
Peak infected          = 300,465 at day 61.4
Final size (simulated) = 0.9404
Final size (theory)    = 0.9405
Theory match           = True

--- sanity checks ---
population_conserved                PASS
compartments_nonnegative            PASS
R_monotonic_increase                PASS

参照モデルを使わなくなったときに重要となるフラグは、--input-json（Model IR リクエストをファイルで指定）と、--approve-heavy（繰り返しの改良実行を許可）です。

# Without --approve-heavy the study is refused rather than run silently.
axiomize model --action numerical-verify --input-json request.json
# status: APPROVAL_REQUIRED, study: solver_tolerance_refinement

axiomize model --action numerical-verify --input-json request.json --approve-heavy
# status: PASS, uncertainty_separation.numerical: 6.6100987239990846e-11

リクエストファイルを含む手順の詳細は、docs/quickstart.md を参照してください。

インターフェース一覧

エンジンは、4つのインターフェースの背後にある68個のパブリックモジュールで構成されています。このREADMEではCLI全体と2つのサーバーの概要を説明します。モジュールごとの詳細は docs/integrations.md を参照してください。

コンソールスクリプト（8個）

コマンド	機能
axiomize	メインのCLIです。以下に示す14個のサブコマンドがあります。
axiomize-validate	3つの参照モデル（sir、gillespie、queue）の閉形式理論チェックを行います
axiomize-fit	time,value CSV に対して sir または logistic を較正します。組み込みチェックは --selftest で実行します
axiomize-csv-check	観測ファイルのデータ品質をチェックします。欠損、重複、修正 z スコアによる外れ値を検出します
axiomize-benchmark	benchmarks/ideas.json 内のケースを基準に、生成されたレポートを評価します
axiomize-to-latex	標準化されたレポートを LaTeX に変換します。オプションで --pdf を指定できます。このプロジェクトで LaTeX を扱う方法はこれだけです。モデルのエクスポート形式ではありません。
axiomize-index-reports	ディレクトリ内のレポートから reports/INDEX.md を再構築します
axiomize-sweep	並列パラメータスイープ（--job sweep、--job mc）を実行します

axiomize のサブコマンド（14個）

intake · policy · model · clean-data · compare-runs · solve · fit · validate · tools · capabilities · reproduce · benchmark · serve · mcp

tools と capabilities はバックエンドの利用可否を報告します。policy はエージェントが使用を許可されているリソースを報告します。reproduce と compare-runs は保存済みの実行ディレクトリを対象に処理します。

axiomize model --action（16個）

ファミリー	値
モデルのライフサイクル	plan · validate · simulate · fit · compare · repair · export
分析	stability · validity · discover · experiment-design · uncertainty · bifurcation
検証	numerical-verify · stop-check · surrogate

MCP と REST

MCP サーバーは、axiomize.<verb> という名前の35個のツールを公開します。axiomize.model_* は上記の model --action の値に対応します。接頭辞のない名前（solve、fit_model、cross_validate、 sensitivity_analysis、uncertainty_analysis、falsify、compare_models、intake、 workflow_policy、clean_data、compare_runs、experiment_design、inspect_run、 reproduce、get_capabilities、list_tools、select_tools）は、周辺のワークフローをカバーします。リストを鵜呑みにせず、列挙して確認してください。

axiomize mcp        # stdio transport; send tools/list over stdin

REST サーバーは、デフォルトでループバック上の /v1 プレフィックス配下に、30個のルートハンドラー（26個の POST に加え、GET /tools、/capabilities、 /workflow-policy、/runs/{id}）を提供します。

axiomize serve --port 8765
curl -s http://127.0.0.1:8765/v1/capabilities

どちらのインターフェースも、READMEで漏れなく列挙できる規模を超えています。そのため、リストよりも命名規則が重要です。どちらの数も、インストール済みのハンドラーを数えたものです。

モデルのエクスポート形式

axiomize model --action export --input-json request.json は、"format" フィールドに基づいて処理を振り分けます。各モデルで実際に PASS を返す形式は次のとおりです。

形式	ステータス	備考
json	はい	正規 Model IR、キーはソート済み
python	はい	IR を再インポートする、再実行可能なスクリプト
yaml	はい	PyYAML が必要です。ない場合は TOOL_UNAVAILABLE
ipynb	はい	nbformat 4 のノートブック
sbml-l3v2	はい	SBML Level 3 Version 2 Core
modelica	はい	Modelica 3.6 テキスト
portable-bundle	はい	正規 IR の SHA-256 を含む axiomize.portable-bundle.v1
graphml	条件付き	metadata.network を持つ family: network IR が必要です
causal-dot	条件付き	識別メタデータを持つ family: causal IR が必要です
cellml-2.0	条件付き	サポート対象の単位では成功します。再解釈しない単位を示す ADAPTER_REQUIRED が返されます
sbml、cellml	いいえ	バージョン指定のないエイリアスは、意図的に ADAPTER_REQUIRED を返します

LaTeX はこの振り分け処理には含まれません。latex、tex、pdf を指定すると、 ValueError: format must be json, python, yaml, sbml, or cellml が発生します。 代わりに、作成済みのレポートには axiomize-to-latex を使用してください。

リポジトリの内容

内容	場所	数
ドメインパック	packs/	12
視点レンズ	skills/axiomize/perspectives/	15
レポートテンプレート	skills/axiomize/templates/	5
実行例	examples/	18 .md + quickstart_sir.py
MCP レジストリマニフェスト	server.json	1

MCP レジストリは server.json を読み取り、axiomize mcp を公開します。その mcp-name 行は、 README をスクレイピングするクライアント向けに、この README の先頭にも記載されています。

導入手順

1. すでに正しいと考えているものを試します。 信頼しているモデルを axiomize-validate で再現します。反論できる結果にエンジンが異議を唱えた場合は、ここで作業を止めて issue を開いてください。
2. 実際の質問を 1 つ Model IR に移します。 単位と制約を明示的に宣言します。 次元チェックの価値は、まずここに表れます。
3. 負荷の高いステップを制御します。 離散化されたファミリーは、 --approve-heavy を渡すまで APPROVAL_REQUIRED を返します。承認によって計算が許可されますが、 リソース上限が無効になることはありません。
4. 移植可能な形式でエクスポートします。 axiomize model --action export は正規 IR JSON と、 サポート対象モデル向けの SBML、CellML、Modelica を出力するため、成果物はこのライブラリがなくても利用できます。
5. レビューに組み込みます。 図だけでなく、エクスポートした IR と検証記録も結果に添えてください。

実際の機能

• 次元の整合性を検証し、メートルに秒を加算できないようにします
• これらのチェックに失敗したモデルのシミュレーションを拒否します。実行時には axiomize model --action validate と同じ検証が行われ、不一致があると数値を返す代わりに、 失敗したチェックを含む ModelDimensionMismatch が発生します
• 科学的制約を、説明文ではなく、名前と根拠を伴うチェックとして適用します
• 収束を主張する前に、数値誤差と確率的変動を分けます
• 候補となるモデルファミリーを比較し、選択理由を記録します
• JSON、Python、YAML、ノートブック、SBML Level 3、CellML 2.0、Modelica、GraphML、 Graphviz DOT、SHA-256 付きポータブルバンドルにエクスポートします。条件付きとなる形式については、 形式の表を参照してください。値と単位はビット単位で正確に往復し、 それを前提とするのではなく、テストスイートで検証しています
• 別の経路である axiomize-to-latex を使って、作成済みのレポートを LaTeX に変換します
• 整合性を検証できる実行台帳を保持するため、保存された結果を利用前に検証できます

正直な制約

• 低性能なモデルを優れたモデルに変えることはできません。低性能なモデルの失敗を明確にするものです。
• ベイズサンプリングには full エクストラ（PyMC／JAX）が必要です。FEM には FEniCS／DOLFINx が必要です。どちらも、黙って別のものに置き換えるのではなく、利用不可として報告されます。
• ベンチマーク結果では、ブラインド実行におけるレポートの構成を評価しており、モデリングの正確さは評価していません。スクリプト、ケースセット、コミットのハッシュを記載した表のみ再現可能です。以前の波は履歴として残しており、再実行できません。
• 実例では、lit.／data／est. とラベル付けした、説明用のパラメーター範囲を使用しています。外部の情報源を引用する例はないため、数値は文献に裏付けられた結果ではなく、読み物として扱ってください。
• 生成コードの実行と定理の詳細化は、OS のサンドボックスではありません。SECURITY.md を参照してください。

ドキュメント

• クイックスタートとワークフロー：furox-art.github.io/axiomize
• 実例：サンプルギャラリー、または examples/ 内の19 個のファイル
• ドメインパック（分野ごとに重要な視点）： packs/domain-packs.md
• エージェント連携（MCP、REST、CLI）：docs/integrations.md
• 移植可能なエクスポート形式：docs/portable-export.md
• 信頼境界とレポート：SECURITY.md、docs/security.md
• エージェントスキルパック：skills/axiomize/SKILL.md と 15 個の視点レンズ

サプライチェーン

PyPI リリースは PEP 740 アテステーション付きで公開されています。wheel と sdist の両方に、release.yml、環境 pypi を介して Furox-Art/axiomize を示す Sigstore バンドルが含まれ、各アテステーションのダイジェストはダウンロードしたファイルと一致します。インストール前に確認できます。

npm リリースにはアテステーションがありません。npm の信頼されたパブリッシャーが登録されていないため、npm の tarball はダイジェストによる検証のみ可能です。現在の npm shim（1.14.1）にはビルドアテステーションがありません。

npm view [email protected] dist.integrity   # pin this; npm ci enforces it from a lockfile

混同しやすいものが 3 つあります。PEP 740 アテステーションは、ビルドワークフローがこのファイルの正確なダイジェストに署名したことを示します。**npm dist.signaturesが示すのは、レジストリが自身のメタデータを改変していないことだけです。すべての npm バージョンに含まれており、トークン方式でも OIDC 方式でも変わりませんが、ビルドの来歴を示すものではありません。dist.integrity／digests.sha256**は、手元にあるバイト列が公開されたバイト列と同じであることを示しますが、誰がビルドしたかは示しません。

現時点で誠実に推奨できるのは、ダイジェストによるピン留めです。npm の信頼されたパブリッシャー（オーナー Furox-Art、リポジトリ axiomize、ワークフロー release.yml、環境 npm）を登録すれば、npm の不足を解消できます。PyPI ではすでに登録されています。検証コマンド、ファイルごとの PyPI エンドポイントの形式、3 つそれぞれが証明する内容については docs/documentation.md を参照してください。また、CI は実行のたびに両方のレジストリに対して、このドキュメントの来歴に関する記述を再確認します。

npm

npx axiomize は動作し、python -m axiomize.cli に処理を渡すため、内部で Python と pip install axiomize が必要です。スタンドアロンのバイナリではありません。npm 1.12.2 は公開済みですが、動作しません（index.js に構文エラーがありました）。最初に動作するリリースは 1.12.4 です。

ライセンス

MIT です。使って、壊して、修正してください。