platformforge 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (659) hide show
  1. platformforge/__init__.py +7 -0
  2. platformforge/__main__.py +5 -0
  3. platformforge/_forge_portal.py +913 -0
  4. platformforge/_graphstudio.py +376 -0
  5. platformforge/_graphview.py +181 -0
  6. platformforge/_installkit.py +1706 -0
  7. platformforge/agents/__init__.py +156 -0
  8. platformforge/agents/bench.py +61 -0
  9. platformforge/agents/contextpack.py +137 -0
  10. platformforge/agents/contracts.py +394 -0
  11. platformforge/agents/coordinators.py +98 -0
  12. platformforge/agents/critic.py +113 -0
  13. platformforge/agents/debate.py +161 -0
  14. platformforge/agents/executors.py +160 -0
  15. platformforge/agents/guardian.py +48 -0
  16. platformforge/agents/mirrors.py +240 -0
  17. platformforge/agents/orchestrator.py +295 -0
  18. platformforge/agents/planner.py +116 -0
  19. platformforge/agents/playbook.py +51 -0
  20. platformforge/agents/referee.py +132 -0
  21. platformforge/agents/reviewers.py +113 -0
  22. platformforge/agents/roster.py +893 -0
  23. platformforge/agents/runledger.py +85 -0
  24. platformforge/agents/runstore.py +74 -0
  25. platformforge/agents/specialists.py +73 -0
  26. platformforge/agents/taskspec.py +94 -0
  27. platformforge/agents/uniqueness.py +115 -0
  28. platformforge/agents/verifier.py +106 -0
  29. platformforge/aiplat/__init__.py +4 -0
  30. platformforge/aiplat/models.py +175 -0
  31. platformforge/analytics/__init__.py +6 -0
  32. platformforge/analytics/capacity.py +109 -0
  33. platformforge/analytics/debt.py +92 -0
  34. platformforge/analytics/dx.py +69 -0
  35. platformforge/analytics/finops_v4.py +171 -0
  36. platformforge/analytics/goldenpath.py +131 -0
  37. platformforge/analytics/history.py +233 -0
  38. platformforge/analytics/measurement.py +149 -0
  39. platformforge/analytics/models.py +127 -0
  40. platformforge/analytics/opsanalytics.py +119 -0
  41. platformforge/analytics/policyintel.py +139 -0
  42. platformforge/analytics/reliability.py +106 -0
  43. platformforge/analytics/soak.py +135 -0
  44. platformforge/analytics/store.py +254 -0
  45. platformforge/bench.py +174 -0
  46. platformforge/cases/__init__.py +13 -0
  47. platformforge/cases/casefile.py +106 -0
  48. platformforge/cases/context_audit.py +134 -0
  49. platformforge/cases/ledgers.py +174 -0
  50. platformforge/cases/replay.py +142 -0
  51. platformforge/cases/routing_audit.py +162 -0
  52. platformforge/caveman/__init__.py +11 -0
  53. platformforge/caveman/compress.py +156 -0
  54. platformforge/cicd/__init__.py +16 -0
  55. platformforge/cicd/backstage.py +51 -0
  56. platformforge/cicd/dockerfile.py +64 -0
  57. platformforge/cicd/github_actions.py +122 -0
  58. platformforge/cicd/gitlab_ci.py +56 -0
  59. platformforge/cicd/gitops.py +130 -0
  60. platformforge/cli/__init__.py +0 -0
  61. platformforge/cli/fleetcmd.py +457 -0
  62. platformforge/cli/main.py +3832 -0
  63. platformforge/cloud/__init__.py +8 -0
  64. platformforge/cloud/aws.py +254 -0
  65. platformforge/cloud/common.py +69 -0
  66. platformforge/cloud/multicloud.py +143 -0
  67. platformforge/collect/__init__.py +11 -0
  68. platformforge/collect/detect.py +254 -0
  69. platformforge/context/__init__.py +10 -0
  70. platformforge/context/capsule.py +60 -0
  71. platformforge/context/gateway.py +227 -0
  72. platformforge/context/refs.py +49 -0
  73. platformforge/context/sufficiency.py +50 -0
  74. platformforge/core/__init__.py +1 -0
  75. platformforge/core/hashing.py +39 -0
  76. platformforge/core/ownership.py +220 -0
  77. platformforge/core/receipts.py +74 -0
  78. platformforge/core/redaction.py +97 -0
  79. platformforge/core/store.py +119 -0
  80. platformforge/core/workspace.py +89 -0
  81. platformforge/data/contracts/agent-handoff.schema.json +26 -0
  82. platformforge/data/contracts/agent-run.schema.json +27 -0
  83. platformforge/data/contracts/agent-spec.schema.json +43 -0
  84. platformforge/data/contracts/capability.schema.json +23 -0
  85. platformforge/data/contracts/change-event.schema.json +22 -0
  86. platformforge/data/contracts/change-intent.schema.json +62 -0
  87. platformforge/data/contracts/change-plan.schema.json +43 -0
  88. platformforge/data/contracts/collector-receipt.schema.json +36 -0
  89. platformforge/data/contracts/context-pack.schema.json +29 -0
  90. platformforge/data/contracts/debate.schema.json +31 -0
  91. platformforge/data/contracts/distribution-manifest-v1.schema.json +81 -0
  92. platformforge/data/contracts/drift-event.schema.json +21 -0
  93. platformforge/data/contracts/fact.schema.json +35 -0
  94. platformforge/data/contracts/finding.schema.json +20 -0
  95. platformforge/data/contracts/graph-v2.schema.json +67 -0
  96. platformforge/data/contracts/graph.schema.json +40 -0
  97. platformforge/data/contracts/install-receipt-v1.schema.json +49 -0
  98. platformforge/data/contracts/observation.schema.json +93 -0
  99. platformforge/data/contracts/receipt.schema.json +21 -0
  100. platformforge/data/contracts/recommendation.schema.json +32 -0
  101. platformforge/data/contracts/refusal.schema.json +16 -0
  102. platformforge/data/contracts/slo-contract.schema.json +25 -0
  103. platformforge/data/contracts/task-spec.schema.json +37 -0
  104. platformforge/data/contracts/workspace-manifest-v1.schema.json +62 -0
  105. platformforge/data/evals/cases/agent-budget-exhaustion/case.yaml +6 -0
  106. platformforge/data/evals/cases/agent-conflicting-specialists/case.yaml +11 -0
  107. platformforge/data/evals/cases/agent-fleet-optimization/case.yaml +13 -0
  108. platformforge/data/evals/cases/agent-host-no-subagents/case.yaml +6 -0
  109. platformforge/data/evals/cases/agent-incident-multi/case.yaml +13 -0
  110. platformforge/data/evals/cases/agent-missing-evidence/case.yaml +6 -0
  111. platformforge/data/evals/cases/agent-multi-domain-audit/case.yaml +14 -0
  112. platformforge/data/evals/cases/agent-production-change/case.yaml +15 -0
  113. platformforge/data/evals/cases/agent-security-mandatory/case.yaml +12 -0
  114. platformforge/data/evals/cases/agent-simple-iac/case.yaml +14 -0
  115. platformforge/data/evals/cases/approval-integrity-seal/case.yaml +6 -0
  116. platformforge/data/evals/cases/capacity-hot/case.yaml +7 -0
  117. platformforge/data/evals/cases/capacity-hot/fixture/capacity.json +5 -0
  118. platformforge/data/evals/cases/catalog-noowner/case.yaml +7 -0
  119. platformforge/data/evals/cases/catalog-noowner/fixture/catalog-info.yaml +6 -0
  120. platformforge/data/evals/cases/contract-fact/case.yaml +5 -0
  121. platformforge/data/evals/cases/contract-fact/fixture/doc.json +2 -0
  122. platformforge/data/evals/cases/cosign-unverified/case.yaml +8 -0
  123. platformforge/data/evals/cases/cosign-unverified/fixture/sig.json +33 -0
  124. platformforge/data/evals/cases/expected-delta-refusal/case.yaml +6 -0
  125. platformforge/data/evals/cases/finops-noattr/case.yaml +9 -0
  126. platformforge/data/evals/cases/finops-noattr/fixture/costs.json +7 -0
  127. platformforge/data/evals/cases/fleet-inv-absent-allocation-unknown/case.yaml +7 -0
  128. platformforge/data/evals/cases/fleet-inv-centrality-not-criticality/case.yaml +7 -0
  129. platformforge/data/evals/cases/fleet-inv-correlation-not-causality/case.yaml +7 -0
  130. platformforge/data/evals/cases/fleet-inv-dx-no-person-metrics/case.yaml +7 -0
  131. platformforge/data/evals/cases/fleet-inv-federation-restricted-denied/case.yaml +7 -0
  132. platformforge/data/evals/cases/fleet-inv-federation-secret-denied/case.yaml +7 -0
  133. platformforge/data/evals/cases/fleet-inv-history-window-deterministic/case.yaml +7 -0
  134. platformforge/data/evals/cases/fleet-inv-low-util-not-deletable/case.yaml +7 -0
  135. platformforge/data/evals/cases/fleet-inv-member-key-deterministic/case.yaml +7 -0
  136. platformforge/data/evals/cases/fleet-inv-missing-denominator/case.yaml +7 -0
  137. platformforge/data/evals/cases/fleet-inv-partial-coverage-visible/case.yaml +7 -0
  138. platformforge/data/evals/cases/fleet-inv-plan-changeintent-only/case.yaml +7 -0
  139. platformforge/data/evals/cases/fleet-inv-report-all-cited/case.yaml +7 -0
  140. platformforge/data/evals/cases/fleet-inv-small-sample-confidence/case.yaml +7 -0
  141. platformforge/data/evals/cases/fleet-inv-uncertain-optimization-suppressed/case.yaml +7 -0
  142. platformforge/data/evals/cases/gha-dangerous/case.yaml +12 -0
  143. platformforge/data/evals/cases/gha-dangerous/fixture/.github/workflows/ci.yaml +11 -0
  144. platformforge/data/evals/cases/gitops-v2/case.yaml +11 -0
  145. platformforge/data/evals/cases/gitops-v2/fixture/argo.yaml +41 -0
  146. platformforge/data/evals/cases/graph-k8s-blast/case.yaml +7 -0
  147. platformforge/data/evals/cases/graph-k8s-blast/fixture/deploy.yaml +15 -0
  148. platformforge/data/evals/cases/iac-module-nopin/case.yaml +8 -0
  149. platformforge/data/evals/cases/iac-module-nopin/fixture/main.tf +3 -0
  150. platformforge/data/evals/cases/iac-plan-replace/case.yaml +8 -0
  151. platformforge/data/evals/cases/iac-plan-replace/fixture/plan.json +12 -0
  152. platformforge/data/evals/cases/iac-sg-open/case.yaml +8 -0
  153. platformforge/data/evals/cases/iac-sg-open/fixture/main.tf +9 -0
  154. platformforge/data/evals/cases/iam-oidc/case.yaml +8 -0
  155. platformforge/data/evals/cases/iam-oidc/fixture/policy.json +11 -0
  156. platformforge/data/evals/cases/iam-wildcard-positive/case.yaml +8 -0
  157. platformforge/data/evals/cases/iam-wildcard-positive/fixture/policy.json +3 -0
  158. platformforge/data/evals/cases/k8s-bad-actor/case.yaml +19 -0
  159. platformforge/data/evals/cases/k8s-bad-actor/fixture/app.yaml +97 -0
  160. platformforge/data/evals/cases/k8s-beta-api/case.yaml +8 -0
  161. platformforge/data/evals/cases/k8s-beta-api/fixture/cr.yaml +7 -0
  162. platformforge/data/evals/cases/k8s-dep-api-boundary/case.yaml +15 -0
  163. platformforge/data/evals/cases/k8s-dep-api-boundary/fixture/app.yaml +25 -0
  164. platformforge/data/evals/cases/k8s-dep-api-clean/case.yaml +12 -0
  165. platformforge/data/evals/cases/k8s-dep-api-clean/fixture/app.yaml +29 -0
  166. platformforge/data/evals/cases/k8s-dep-api-unknown/case.yaml +11 -0
  167. platformforge/data/evals/cases/k8s-dep-api-unknown/fixture/app.yaml +25 -0
  168. platformforge/data/evals/cases/k8s-dep-api-v120/case.yaml +12 -0
  169. platformforge/data/evals/cases/k8s-dep-api-v120/fixture/app.yaml +25 -0
  170. platformforge/data/evals/cases/k8s-dep-api-v129/case.yaml +9 -0
  171. platformforge/data/evals/cases/k8s-dep-api-v129/fixture/app.yaml +25 -0
  172. platformforge/data/evals/cases/k8s-hpa-noreq/case.yaml +8 -0
  173. platformforge/data/evals/cases/k8s-hpa-noreq/fixture/app.yaml +28 -0
  174. platformforge/data/evals/cases/k8s-limits-boundary/case.yaml +10 -0
  175. platformforge/data/evals/cases/k8s-limits-boundary/fixture/app.yaml +15 -0
  176. platformforge/data/evals/cases/k8s-limits-negative/case.yaml +8 -0
  177. platformforge/data/evals/cases/k8s-limits-negative/fixture/deploy.yaml +15 -0
  178. platformforge/data/evals/cases/k8s-limits-positive/case.yaml +8 -0
  179. platformforge/data/evals/cases/k8s-limits-positive/fixture/deploy.yaml +14 -0
  180. platformforge/data/evals/cases/k8s-nopdb/case.yaml +7 -0
  181. platformforge/data/evals/cases/k8s-nopdb/fixture/app.yaml +34 -0
  182. platformforge/data/evals/cases/knowledge-registry/case.yaml +10 -0
  183. platformforge/data/evals/cases/kyverno-dep/case.yaml +10 -0
  184. platformforge/data/evals/cases/kyverno-dep/fixture/pol.yaml +18 -0
  185. platformforge/data/evals/cases/kyverno-legacy/case.yaml +8 -0
  186. platformforge/data/evals/cases/kyverno-legacy/fixture/pol.yaml +7 -0
  187. platformforge/data/evals/cases/live-aws-collect/case.yaml +11 -0
  188. platformforge/data/evals/cases/live-aws-collect/fixture/aws/ec2_describe-vpcs.json +15 -0
  189. platformforge/data/evals/cases/live-aws-collect/fixture/aws/iam_list-users.denied.txt +1 -0
  190. platformforge/data/evals/cases/live-aws-collect/fixture/aws/sts_get-caller-identity.json +5 -0
  191. platformforge/data/evals/cases/live-drift/case.yaml +8 -0
  192. platformforge/data/evals/cases/live-drift/fixture/after.json +22 -0
  193. platformforge/data/evals/cases/live-drift/fixture/before.json +22 -0
  194. platformforge/data/evals/cases/live-incident/case.yaml +7 -0
  195. platformforge/data/evals/cases/live-incident/fixture/changes.json +8 -0
  196. platformforge/data/evals/cases/live-incident/fixture/incident.json +7 -0
  197. platformforge/data/evals/cases/live-k8s-collect/case.yaml +10 -0
  198. platformforge/data/evals/cases/live-k8s-collect/fixture/kubectl/get_configmaps.denied.txt +1 -0
  199. platformforge/data/evals/cases/live-k8s-collect/fixture/kubectl/get_deployments.apps.json +25 -0
  200. platformforge/data/evals/cases/live-k8s-collect/fixture/kubectl/get_pods.json +17 -0
  201. platformforge/data/evals/cases/live-k8s-collect/fixture/kubectl/get_secrets.json +13 -0
  202. platformforge/data/evals/cases/live-multicluster/case.yaml +7 -0
  203. platformforge/data/evals/cases/live-multicluster/fixture/clusters.json +6 -0
  204. platformforge/data/evals/cases/live-plan/case.yaml +7 -0
  205. platformforge/data/evals/cases/live-plan/fixture/drift.json +8 -0
  206. platformforge/data/evals/cases/live-reconcile/case.yaml +7 -0
  207. platformforge/data/evals/cases/live-reconcile/fixture/desired.json +7 -0
  208. platformforge/data/evals/cases/live-reconcile/fixture/observed.json +18 -0
  209. platformforge/data/evals/cases/live-secrets-boundary/case.yaml +8 -0
  210. platformforge/data/evals/cases/live-secrets-boundary/fixture/envelope.json +16 -0
  211. platformforge/data/evals/cases/live-temporal-graph/case.yaml +10 -0
  212. platformforge/data/evals/cases/live-temporal-graph/fixture/graph.json +22 -0
  213. platformforge/data/evals/cases/ops-approval/case.yaml +6 -0
  214. platformforge/data/evals/cases/ops-convergence/case.yaml +6 -0
  215. platformforge/data/evals/cases/ops-execution-safety/case.yaml +6 -0
  216. platformforge/data/evals/cases/ops-intent/case.yaml +6 -0
  217. platformforge/data/evals/cases/ops-planning/case.yaml +6 -0
  218. platformforge/data/evals/cases/ops-policy/case.yaml +6 -0
  219. platformforge/data/evals/cases/ops-rollback/case.yaml +6 -0
  220. platformforge/data/evals/cases/ops-verification/case.yaml +6 -0
  221. platformforge/data/evals/cases/rollback-argocd-revision/case.yaml +6 -0
  222. platformforge/data/evals/cases/rollback-blind-inverse/case.yaml +6 -0
  223. platformforge/data/evals/cases/rollback-git-commit/case.yaml +6 -0
  224. platformforge/data/evals/cases/rollback-impossible/case.yaml +6 -0
  225. platformforge/data/evals/cases/rollback-k8s-annotation-restore/case.yaml +6 -0
  226. platformforge/data/evals/cases/rollback-k8s-scale/case.yaml +6 -0
  227. platformforge/data/evals/cases/rollback-material-tamper/case.yaml +6 -0
  228. platformforge/data/evals/cases/rollback-terraform-replan/case.yaml +6 -0
  229. platformforge/data/evals/cases/rollback-unknown/case.yaml +6 -0
  230. platformforge/data/evals/cases/routing-specialist/case.yaml +9 -0
  231. platformforge/data/evals/cases/rtk-roundtrip/case.yaml +5 -0
  232. platformforge/data/evals/cases/rtk-roundtrip/fixture/verbose.txt +300 -0
  233. platformforge/data/evals/cases/sbom-vuln/case.yaml +9 -0
  234. platformforge/data/evals/cases/sbom-vuln/fixture/sbom.json +9 -0
  235. platformforge/data/evals/cases/secret-prose-mixed/fixture/app.env +1 -0
  236. platformforge/data/evals/cases/secret-prose-mixed/fixture/policy-notes.md +7 -0
  237. platformforge/data/evals/cases/secrets-noleak/case.yaml +5 -0
  238. platformforge/data/evals/cases/secrets-noleak/fixture/app.env +2 -0
  239. platformforge/data/evals/cases/slo-fastburn/case.yaml +8 -0
  240. platformforge/data/evals/cases/slo-fastburn/fixture/events.yaml +2 -0
  241. platformforge/data/evals/cases/slo-fastburn/fixture/slo.yaml +4 -0
  242. platformforge/data/evals/cases/slo-noinput/case.yaml +8 -0
  243. platformforge/data/evals/cases/slo-noinput/fixture/events.yaml +1 -0
  244. platformforge/data/evals/cases/slo-noinput/fixture/slo.yaml +4 -0
  245. platformforge/data/evals/cases/sot-conflict/case.yaml +6 -0
  246. platformforge/data/evals/cases/token-budget/case.yaml +6 -0
  247. platformforge/data/evals/cases/token-budget/fixture/big.py +50 -0
  248. platformforge/data/evals/cases/xr-delete/case.yaml +8 -0
  249. platformforge/data/evals/cases/xr-delete/fixture/xr.yaml +10 -0
  250. platformforge/data/evals/cases/xr-graph-chain/case.yaml +8 -0
  251. platformforge/data/evals/cases/xr-graph-chain/fixture/xrd.yaml +90 -0
  252. platformforge/data/evals/cases/xr-negative-crd/case.yaml +8 -0
  253. platformforge/data/evals/cases/xr-negative-crd/fixture/widget.yaml +19 -0
  254. platformforge/data/evals/cases/xr-upbound-mr/case.yaml +8 -0
  255. platformforge/data/evals/cases/xr-upbound-mr/fixture/bucket.yaml +12 -0
  256. platformforge/data/evals/qpt-bench/change-review/case.yaml +5 -0
  257. platformforge/data/evals/qpt-bench/change-review/fixture/plan.json +9 -0
  258. platformforge/data/evals/qpt-bench/gha-security/case.yaml +5 -0
  259. platformforge/data/evals/qpt-bench/gha-security/fixture/ci.yml +10 -0
  260. platformforge/data/evals/qpt-bench/iam-investigate/case.yaml +5 -0
  261. platformforge/data/evals/qpt-bench/iam-investigate/fixture/policy.json +6 -0
  262. platformforge/data/evals/qpt-bench/incident-analysis/case.yaml +5 -0
  263. platformforge/data/evals/qpt-bench/incident-analysis/fixture/query.json +5 -0
  264. platformforge/data/evals/qpt-bench/incident-analysis/fixture/rules.yaml +6 -0
  265. platformforge/data/evals/qpt-bench/k8s-review/case.yaml +6 -0
  266. platformforge/data/evals/qpt-bench/k8s-review/fixture/deploy.yaml +15 -0
  267. platformforge/data/evals/qpt-bench/tf-security/case.yaml +5 -0
  268. platformforge/data/evals/qpt-bench/tf-security/fixture/main.tf +17 -0
  269. platformforge/data/knowledge/aws/eks.yaml +20 -0
  270. platformforge/data/knowledge/aws/iam.yaml +28 -0
  271. platformforge/data/knowledge/aws/network-exposure.yaml +19 -0
  272. platformforge/data/knowledge/aws/organizations.yaml +19 -0
  273. platformforge/data/knowledge/crossplane/composition-providers.yaml +20 -0
  274. platformforge/data/knowledge/crossplane/managed-resources.yaml +26 -0
  275. platformforge/data/knowledge/crossplane/v1-v2.yaml +25 -0
  276. platformforge/data/knowledge/kubernetes/api-deprecations.yaml +33 -0
  277. platformforge/data/knowledge/kubernetes/autoscaling-rbac.yaml +27 -0
  278. platformforge/data/knowledge/kubernetes/gateway-api.yaml +20 -0
  279. platformforge/data/knowledge/kubernetes/pod-security.yaml +26 -0
  280. platformforge/data/knowledge/sources.yaml +516 -0
  281. platformforge/data/knowledge/terraform/lifecycle.yaml +18 -0
  282. platformforge/data/knowledge/terraform/plan-semantics.yaml +26 -0
  283. platformforge/data/lab/chaos-pod-kill/chaos.yaml +3 -0
  284. platformforge/data/lab/chaos-pod-kill/facts.json +13 -0
  285. platformforge/data/lab/fleets/acme/capacity.yaml +35 -0
  286. platformforge/data/lab/fleets/acme/costs.yaml +25 -0
  287. platformforge/data/lab/fleets/acme/events.yaml +41 -0
  288. platformforge/data/lab/fleets/acme/fleet.yaml +51 -0
  289. platformforge/data/lab/fleets/acme/graph.yaml +45 -0
  290. platformforge/data/lab/fleets/acme/policies.yaml +28 -0
  291. platformforge/data/lab/fleets/acme/requests.yaml +24 -0
  292. platformforge/data/lab/scenarios/argo-bad-rollout/expected.yaml +6 -0
  293. platformforge/data/lab/scenarios/argo-bad-rollout/fixture/app.yaml +9 -0
  294. platformforge/data/lab/scenarios/aws-dump/expected.yaml +19 -0
  295. platformforge/data/lab/scenarios/aws-dump/fixture/compute.json +4 -0
  296. platformforge/data/lab/scenarios/aws-dump/fixture/iam.json +7 -0
  297. platformforge/data/lab/scenarios/aws-dump/fixture/network.json +6 -0
  298. platformforge/data/lab/scenarios/aws-dump/fixture/org.json +4 -0
  299. platformforge/data/lab/scenarios/aws-dump/fixture/storage.json +4 -0
  300. platformforge/data/lab/scenarios/container-unsigned/expected.yaml +5 -0
  301. platformforge/data/lab/scenarios/container-unsigned/fixture/supply.json +11 -0
  302. platformforge/data/lab/scenarios/cost-idle-workload/expected.yaml +5 -0
  303. platformforge/data/lab/scenarios/cost-idle-workload/fixture/costs.json +12 -0
  304. platformforge/data/lab/scenarios/crossplane-platform/expected.yaml +16 -0
  305. platformforge/data/lab/scenarios/crossplane-platform/fixture/negative.yaml +18 -0
  306. platformforge/data/lab/scenarios/crossplane-platform/fixture/xrd.yaml +90 -0
  307. platformforge/data/lab/scenarios/demo-platform/expected.yaml +16 -0
  308. platformforge/data/lab/scenarios/demo-platform/fixture/.github/workflows/ci.yml +10 -0
  309. platformforge/data/lab/scenarios/demo-platform/fixture/deploy.yaml +16 -0
  310. platformforge/data/lab/scenarios/demo-platform/fixture/infra.tf +5 -0
  311. platformforge/data/lab/scenarios/fleet-ai/expected.yaml +12 -0
  312. platformforge/data/lab/scenarios/fleet-capacity/expected.yaml +12 -0
  313. platformforge/data/lab/scenarios/fleet-cost/expected.yaml +18 -0
  314. platformforge/data/lab/scenarios/fleet-federation/expected.yaml +11 -0
  315. platformforge/data/lab/scenarios/fleet-golden-path/expected.yaml +18 -0
  316. platformforge/data/lab/scenarios/fleet-op-hotspot/expected.yaml +11 -0
  317. platformforge/data/lab/scenarios/fleet-ownership/expected.yaml +17 -0
  318. platformforge/data/lab/scenarios/fleet-partial/expected.yaml +10 -0
  319. platformforge/data/lab/scenarios/fleet-policy-friction/expected.yaml +10 -0
  320. platformforge/data/lab/scenarios/fleet-recurring-incident/expected.yaml +12 -0
  321. platformforge/data/lab/scenarios/fleet-report/expected.yaml +13 -0
  322. platformforge/data/lab/scenarios/fleet-risk/expected.yaml +18 -0
  323. platformforge/data/lab/scenarios/gitops-drift/expected.yaml +6 -0
  324. platformforge/data/lab/scenarios/gitops-drift/fixture/app.yaml +12 -0
  325. platformforge/data/lab/scenarios/k8s-bad-readiness/expected.yaml +6 -0
  326. platformforge/data/lab/scenarios/k8s-bad-readiness/fixture/deploy.yaml +23 -0
  327. platformforge/data/lab/scenarios/k8s-bad-readiness/fixture/netpol.yaml +9 -0
  328. platformforge/data/lab/scenarios/k8s-missing-limits/expected.yaml +6 -0
  329. platformforge/data/lab/scenarios/k8s-missing-limits/fixture/deploy.yaml +26 -0
  330. platformforge/data/lab/scenarios/k8s-missing-limits/fixture/netpol.yaml +9 -0
  331. platformforge/data/lab/scenarios/k8s-single-replica/expected.yaml +5 -0
  332. platformforge/data/lab/scenarios/k8s-single-replica/fixture/deploy.yaml +26 -0
  333. platformforge/data/lab/scenarios/k8s-single-replica/fixture/netpol.yaml +4 -0
  334. platformforge/data/lab/scenarios/live-aws-collect/expected.yaml +4 -0
  335. platformforge/data/lab/scenarios/live-aws-collect/fixture/aws/ec2_describe-vpcs.json +15 -0
  336. platformforge/data/lab/scenarios/live-aws-collect/fixture/aws/iam_list-users.denied.txt +1 -0
  337. platformforge/data/lab/scenarios/live-aws-collect/fixture/aws/sts_get-caller-identity.json +5 -0
  338. platformforge/data/lab/scenarios/live-k8s-collect/expected.yaml +4 -0
  339. platformforge/data/lab/scenarios/live-k8s-collect/fixture/kubectl/get_configmaps.denied.txt +1 -0
  340. platformforge/data/lab/scenarios/live-k8s-collect/fixture/kubectl/get_deployments.apps.json +25 -0
  341. platformforge/data/lab/scenarios/live-k8s-collect/fixture/kubectl/get_pods.json +17 -0
  342. platformforge/data/lab/scenarios/live-k8s-collect/fixture/kubectl/get_secrets.json +13 -0
  343. platformforge/data/lab/scenarios/live-kind/expected.yaml +14 -0
  344. platformforge/data/lab/scenarios/live-kind/fixture/kubectl/get_configmaps.denied.txt +1 -0
  345. platformforge/data/lab/scenarios/live-kind/fixture/kubectl/get_deployments.apps.json +25 -0
  346. platformforge/data/lab/scenarios/live-kind/fixture/kubectl/get_pods.json +17 -0
  347. platformforge/data/lab/scenarios/live-kind/fixture/kubectl/get_secrets.json +13 -0
  348. platformforge/data/lab/scenarios/network-policy-missing/expected.yaml +6 -0
  349. platformforge/data/lab/scenarios/network-policy-missing/fixture/deploy.yaml +26 -0
  350. platformforge/data/lab/scenarios/ops-bad-rollout/expected.yaml +3 -0
  351. platformforge/data/lab/scenarios/ops-bad-rollout/fixture/ops.yaml +33 -0
  352. platformforge/data/lab/scenarios/ops-break-glass/expected.yaml +3 -0
  353. platformforge/data/lab/scenarios/ops-break-glass/fixture/ops.yaml +21 -0
  354. platformforge/data/lab/scenarios/ops-broken-selector/expected.yaml +3 -0
  355. platformforge/data/lab/scenarios/ops-broken-selector/fixture/ops.yaml +21 -0
  356. platformforge/data/lab/scenarios/ops-changed-plan-hash/expected.yaml +3 -0
  357. platformforge/data/lab/scenarios/ops-changed-plan-hash/fixture/ops.yaml +20 -0
  358. platformforge/data/lab/scenarios/ops-conflicting-operation/expected.yaml +3 -0
  359. platformforge/data/lab/scenarios/ops-conflicting-operation/fixture/ops.yaml +21 -0
  360. platformforge/data/lab/scenarios/ops-expired-approval/expected.yaml +3 -0
  361. platformforge/data/lab/scenarios/ops-expired-approval/fixture/ops.yaml +20 -0
  362. platformforge/data/lab/scenarios/ops-partial-failure/expected.yaml +3 -0
  363. platformforge/data/lab/scenarios/ops-partial-failure/fixture/ops.yaml +24 -0
  364. platformforge/data/lab/scenarios/ops-policy-denial/expected.yaml +3 -0
  365. platformforge/data/lab/scenarios/ops-policy-denial/fixture/ops.yaml +17 -0
  366. platformforge/data/lab/scenarios/ops-replica-drift/expected.yaml +3 -0
  367. platformforge/data/lab/scenarios/ops-replica-drift/fixture/ops.yaml +28 -0
  368. platformforge/data/lab/scenarios/ops-rollback-annotate/expected.yaml +3 -0
  369. platformforge/data/lab/scenarios/ops-rollback-annotate/fixture/ops.yaml +41 -0
  370. platformforge/data/lab/scenarios/ops-rollback-gitops/expected.yaml +3 -0
  371. platformforge/data/lab/scenarios/ops-rollback-gitops/fixture/ops.yaml +38 -0
  372. platformforge/data/lab/scenarios/ops-rollback-impossible/expected.yaml +3 -0
  373. platformforge/data/lab/scenarios/ops-rollback-impossible/fixture/ops.yaml +34 -0
  374. platformforge/data/lab/scenarios/ops-rollback-scale/expected.yaml +3 -0
  375. platformforge/data/lab/scenarios/ops-rollback-scale/fixture/ops.yaml +40 -0
  376. platformforge/data/lab/scenarios/ops-rollback-terraform/expected.yaml +3 -0
  377. platformforge/data/lab/scenarios/ops-rollback-terraform/fixture/ops.yaml +38 -0
  378. platformforge/data/lab/scenarios/ops-rollback-terraform/fixture/tf/tfplan.bin +1 -0
  379. platformforge/data/lab/scenarios/ops-stale-observation/expected.yaml +3 -0
  380. platformforge/data/lab/scenarios/ops-stale-observation/fixture/ops.yaml +20 -0
  381. platformforge/data/lab/scenarios/secret-exposure/expected.yaml +5 -0
  382. platformforge/data/lab/scenarios/secret-exposure/fixture/app.env +2 -0
  383. platformforge/data/lab/scenarios/slo-burn/expected.yaml +5 -0
  384. platformforge/data/lab/scenarios/slo-burn/fixture/events.yaml +2 -0
  385. platformforge/data/lab/scenarios/slo-burn/fixture/slo.yaml +4 -0
  386. platformforge/data/lab/scenarios/terraform-iam-wildcard/expected.yaml +5 -0
  387. platformforge/data/lab/scenarios/terraform-iam-wildcard/fixture/policy.json +14 -0
  388. platformforge/data/lab/scenarios/terraform-public-bucket/expected.yaml +6 -0
  389. platformforge/data/lab/scenarios/terraform-public-bucket/fixture/main.tf +5 -0
  390. platformforge/data/portable_skills/platformforge-agents/SKILL.md +47 -0
  391. platformforge/data/portable_skills/platformforge-change/SKILL.md +41 -0
  392. platformforge/data/portable_skills/platformforge-core/SKILL.md +62 -0
  393. platformforge/data/portable_skills/platformforge-economy/SKILL.md +42 -0
  394. platformforge/data/portable_skills/platformforge-finops/SKILL.md +34 -0
  395. platformforge/data/portable_skills/platformforge-fleet/SKILL.md +39 -0
  396. platformforge/data/portable_skills/platformforge-governance/SKILL.md +76 -0
  397. platformforge/data/portable_skills/platformforge-graph/SKILL.md +46 -0
  398. platformforge/data/portable_skills/platformforge-lab/SKILL.md +39 -0
  399. platformforge/data/portable_skills/platformforge-sdd/SKILL.md +39 -0
  400. platformforge/data/portable_skills/platformforge-security/SKILL.md +38 -0
  401. platformforge/data/portable_skills/platformforge-sre/SKILL.md +41 -0
  402. platformforge/data/rules/catalog/finops.yaml +26 -0
  403. platformforge/data/rules/catalog/gitops.yaml +161 -0
  404. platformforge/data/rules/catalog/iac.yaml +84 -0
  405. platformforge/data/rules/catalog/k8s.yaml +322 -0
  406. platformforge/data/rules/catalog/orchestration.yaml +99 -0
  407. platformforge/data/rules/catalog/product.yaml +42 -0
  408. platformforge/data/rules/catalog/routing.yaml +122 -0
  409. platformforge/data/rules/catalog/security.yaml +159 -0
  410. platformforge/data/rules/catalog/sre.yaml +67 -0
  411. platformforge/diagnose/__init__.py +75 -0
  412. platformforge/distribution/__init__.py +18 -0
  413. platformforge/distribution/bundle.py +127 -0
  414. platformforge/distribution/hostflow.py +247 -0
  415. platformforge/distribution/models.py +80 -0
  416. platformforge/distribution/service.py +225 -0
  417. platformforge/economy/__init__.py +27 -0
  418. platformforge/economy/bench.py +66 -0
  419. platformforge/economy/budget.py +198 -0
  420. platformforge/economy/cache.py +287 -0
  421. platformforge/economy/checkpoint.py +112 -0
  422. platformforge/economy/collection.py +142 -0
  423. platformforge/economy/doctor.py +207 -0
  424. platformforge/economy/engine.py +158 -0
  425. platformforge/economy/envelope.py +61 -0
  426. platformforge/economy/fleetpack.py +86 -0
  427. platformforge/economy/ledger.py +232 -0
  428. platformforge/economy/plan.py +131 -0
  429. platformforge/economy/pricing.py +101 -0
  430. platformforge/economy/qpt.py +286 -0
  431. platformforge/economy/reconcile.py +86 -0
  432. platformforge/economy/verifyplan.py +107 -0
  433. platformforge/economy/waste.py +123 -0
  434. platformforge/evals/__init__.py +16 -0
  435. platformforge/evals/coverage.py +140 -0
  436. platformforge/evals/fleet_invariants.py +260 -0
  437. platformforge/evals/ops_invariants.py +158 -0
  438. platformforge/evals/runner.py +541 -0
  439. platformforge/federation/__init__.py +4 -0
  440. platformforge/federation/node.py +135 -0
  441. platformforge/finops/__init__.py +14 -0
  442. platformforge/finops/alloc.py +31 -0
  443. platformforge/finops/costs.py +79 -0
  444. platformforge/finops/focus.py +100 -0
  445. platformforge/finops/graph_cost.py +51 -0
  446. platformforge/finops/ingest.py +144 -0
  447. platformforge/finops/insights.py +193 -0
  448. platformforge/finops/unit.py +36 -0
  449. platformforge/fleet/__init__.py +5 -0
  450. platformforge/fleet/loader.py +73 -0
  451. platformforge/fleet/models.py +155 -0
  452. platformforge/fleet/orggraph.py +172 -0
  453. platformforge/fleet/query.py +154 -0
  454. platformforge/forge/__init__.py +9 -0
  455. platformforge/forge/collect.py +88 -0
  456. platformforge/forge/delegate.py +77 -0
  457. platformforge/forge/manifest.py +106 -0
  458. platformforge/freeze/__init__.py +22 -0
  459. platformforge/freeze/exceptions.py +56 -0
  460. platformforge/freeze/manifest.py +167 -0
  461. platformforge/freeze/snapshots.py +108 -0
  462. platformforge/graph/__init__.py +39 -0
  463. platformforge/graph/backend.py +174 -0
  464. platformforge/graph/bench.py +245 -0
  465. platformforge/graph/build.py +130 -0
  466. platformforge/graph/delivery.py +183 -0
  467. platformforge/graph/diff.py +292 -0
  468. platformforge/graph/events.py +116 -0
  469. platformforge/graph/migrate.py +44 -0
  470. platformforge/graph/model.py +264 -0
  471. platformforge/graph/persist.py +97 -0
  472. platformforge/graph/query.py +290 -0
  473. platformforge/graph/temporal.py +78 -0
  474. platformforge/graph/vocab.py +63 -0
  475. platformforge/graphview.py +94 -0
  476. platformforge/iac/__init__.py +7 -0
  477. platformforge/iac/drift.py +53 -0
  478. platformforge/iac/plan.py +84 -0
  479. platformforge/iac/terraform.py +123 -0
  480. platformforge/install/__init__.py +1 -0
  481. platformforge/install/service.py +421 -0
  482. platformforge/k8s/__init__.py +8 -0
  483. platformforge/k8s/helm.py +152 -0
  484. platformforge/k8s/hubble.py +87 -0
  485. platformforge/k8s/manifests.py +513 -0
  486. platformforge/knowledge/__init__.py +1 -0
  487. platformforge/knowledge/packs.py +157 -0
  488. platformforge/knowledge/registry.py +249 -0
  489. platformforge/knowledge/select.py +127 -0
  490. platformforge/lab/__init__.py +5 -0
  491. platformforge/lab/chaos.py +71 -0
  492. platformforge/lab/fleetlab.py +351 -0
  493. platformforge/lab/opslab.py +271 -0
  494. platformforge/lab/runner.py +219 -0
  495. platformforge/live/__init__.py +36 -0
  496. platformforge/live/budget.py +92 -0
  497. platformforge/live/capability.py +80 -0
  498. platformforge/live/collectors/__init__.py +6 -0
  499. platformforge/live/collectors/aws.py +370 -0
  500. platformforge/live/collectors/aws_transport.py +98 -0
  501. platformforge/live/collectors/k8s.py +389 -0
  502. platformforge/live/collectors/k8s_transport.py +85 -0
  503. platformforge/live/cursors.py +48 -0
  504. platformforge/live/drift.py +130 -0
  505. platformforge/live/envelope.py +85 -0
  506. platformforge/live/federation.py +113 -0
  507. platformforge/live/fixtures.py +168 -0
  508. platformforge/live/identity.py +258 -0
  509. platformforge/live/incident.py +200 -0
  510. platformforge/live/models.py +435 -0
  511. platformforge/live/reconcile.py +382 -0
  512. platformforge/live/remediate.py +169 -0
  513. platformforge/live/store.py +256 -0
  514. platformforge/live/topology.py +249 -0
  515. platformforge/mcp/__init__.py +7 -0
  516. platformforge/mcp/parity.py +69 -0
  517. platformforge/mcp/registry.py +427 -0
  518. platformforge/mcp/server.py +84 -0
  519. platformforge/mcp/tools.py +732 -0
  520. platformforge/models/__init__.py +21 -0
  521. platformforge/models/base.py +214 -0
  522. platformforge/observe/__init__.py +26 -0
  523. platformforge/observe/capacity.py +39 -0
  524. platformforge/observe/dr.py +67 -0
  525. platformforge/observe/grafana.py +76 -0
  526. platformforge/observe/incident.py +58 -0
  527. platformforge/observe/otel.py +135 -0
  528. platformforge/observe/postmortem.py +72 -0
  529. platformforge/observe/prometheus.py +88 -0
  530. platformforge/observe/slo.py +125 -0
  531. platformforge/ops/__init__.py +8 -0
  532. platformforge/ops/actions.py +215 -0
  533. platformforge/ops/analytics.py +83 -0
  534. platformforge/ops/approval.py +275 -0
  535. platformforge/ops/autorem.py +101 -0
  536. platformforge/ops/config.py +175 -0
  537. platformforge/ops/engine.py +758 -0
  538. platformforge/ops/envelope.py +135 -0
  539. platformforge/ops/executors/__init__.py +1 -0
  540. platformforge/ops/executors/base.py +211 -0
  541. platformforge/ops/executors/git.py +77 -0
  542. platformforge/ops/executors/gitops.py +134 -0
  543. platformforge/ops/executors/terraform.py +84 -0
  544. platformforge/ops/gates.py +135 -0
  545. platformforge/ops/goldenpath.py +180 -0
  546. platformforge/ops/material.py +181 -0
  547. platformforge/ops/models.py +421 -0
  548. platformforge/ops/operation.py +335 -0
  549. platformforge/ops/opgraph.py +233 -0
  550. platformforge/ops/policy.py +275 -0
  551. platformforge/ops/preconditions.py +109 -0
  552. platformforge/ops/registry.py +101 -0
  553. platformforge/ops/risk.py +216 -0
  554. platformforge/ops/rollback.py +287 -0
  555. platformforge/ops/rollback_builders.py +163 -0
  556. platformforge/ops/runbook.py +269 -0
  557. platformforge/ops/simulate.py +125 -0
  558. platformforge/ops/source_of_truth.py +198 -0
  559. platformforge/ops/store.py +157 -0
  560. platformforge/ops/verify.py +190 -0
  561. platformforge/optimize/__init__.py +4 -0
  562. platformforge/optimize/engine.py +109 -0
  563. platformforge/optimize/models.py +68 -0
  564. platformforge/optimize/scan.py +196 -0
  565. platformforge/plan/__init__.py +107 -0
  566. platformforge/portable_cli.py +199 -0
  567. platformforge/portal_adapter.py +740 -0
  568. platformforge/portal_assets/chunk-7_l-b4Tr.js +1 -0
  569. platformforge/portal_assets/chunk-B0Iad6pD.js +1 -0
  570. platformforge/portal_assets/chunk-B605XnCF.js +1 -0
  571. platformforge/portal_assets/chunk-B7N3TXcn.js +1 -0
  572. platformforge/portal_assets/chunk-BAj6yGem.js +1 -0
  573. platformforge/portal_assets/chunk-BGUitn2r.js +1 -0
  574. platformforge/portal_assets/chunk-BVKnCv85.js +1 -0
  575. platformforge/portal_assets/chunk-BYyM9V_w.js +1 -0
  576. platformforge/portal_assets/chunk-BaQMhq-G.js +1 -0
  577. platformforge/portal_assets/chunk-BavOrxVm.js +1 -0
  578. platformforge/portal_assets/chunk-Bb0C24YV.js +1 -0
  579. platformforge/portal_assets/chunk-BfCFGPzs.js +1 -0
  580. platformforge/portal_assets/chunk-C2t4OUVu.js +1 -0
  581. platformforge/portal_assets/chunk-C3pI4QjU.js +1 -0
  582. platformforge/portal_assets/chunk-C4gpbtbP.js +1 -0
  583. platformforge/portal_assets/chunk-CGWeHhKY.js +1 -0
  584. platformforge/portal_assets/chunk-CJCT86Dr.js +1 -0
  585. platformforge/portal_assets/chunk-CXcsLDPJ.js +1 -0
  586. platformforge/portal_assets/chunk-CcjxoLxw.js +1 -0
  587. platformforge/portal_assets/chunk-D-gBPXHa.js +1 -0
  588. platformforge/portal_assets/chunk-D3eZogIe.js +1 -0
  589. platformforge/portal_assets/chunk-DQU0VyoQ.js +1 -0
  590. platformforge/portal_assets/chunk-DqWNkF1O.js +1 -0
  591. platformforge/portal_assets/chunk-DuPPkSIE.js +3 -0
  592. platformforge/portal_assets/chunk-DyIHOW_a.js +1 -0
  593. platformforge/portal_assets/chunk-Fx4zSGL5.js +1 -0
  594. platformforge/portal_assets/chunk-UBKt05Rg.js +1 -0
  595. platformforge/portal_assets/chunk-htnJDQEY.js +1 -0
  596. platformforge/portal_assets/chunk-kXRFMGqe.js +1 -0
  597. platformforge/portal_assets/chunk-qe3u763a.js +1 -0
  598. platformforge/portal_assets/favicon.ico +0 -0
  599. platformforge/portal_assets/index.html +13 -0
  600. platformforge/portal_assets/main-QDFVZK3T.js +5 -0
  601. platformforge/portal_assets/styles-MQEBDFDX.css +1 -0
  602. platformforge/product/__init__.py +10 -0
  603. platformforge/product/backstage.py +49 -0
  604. platformforge/product/catalog.py +74 -0
  605. platformforge/product/crossplane.py +341 -0
  606. platformforge/product/golden_paths/__init__.py +5 -0
  607. platformforge/product/golden_paths/engine.py +97 -0
  608. platformforge/product/golden_paths/library.yaml +198 -0
  609. platformforge/product/golden_paths/model.py +84 -0
  610. platformforge/product/maturity.py +107 -0
  611. platformforge/product/scorecards.py +84 -0
  612. platformforge/resources.py +36 -0
  613. platformforge/risk/__init__.py +5 -0
  614. platformforge/risk/engine.py +95 -0
  615. platformforge/risk/signals.py +49 -0
  616. platformforge/routing/__init__.py +13 -0
  617. platformforge/routing/decision.py +191 -0
  618. platformforge/routing/router.py +328 -0
  619. platformforge/rtk/__init__.py +9 -0
  620. platformforge/rtk/compact.py +127 -0
  621. platformforge/rtk/parsers.py +199 -0
  622. platformforge/rules/__init__.py +5 -0
  623. platformforge/rules/engine.py +345 -0
  624. platformforge/sandbox/__init__.py +7 -0
  625. platformforge/sandbox/env.py +151 -0
  626. platformforge/sandbox/review.py +92 -0
  627. platformforge/sdd/__init__.py +8 -0
  628. platformforge/sdd/lifecycle.py +239 -0
  629. platformforge/security/__init__.py +19 -0
  630. platformforge/security/cosign.py +67 -0
  631. platformforge/security/iam.py +112 -0
  632. platformforge/security/identity.py +84 -0
  633. platformforge/security/kyverno.py +106 -0
  634. platformforge/security/sbom.py +59 -0
  635. platformforge/security/scan.py +63 -0
  636. platformforge/security/slsa.py +86 -0
  637. platformforge/security/supply.py +62 -0
  638. platformforge/tokensave/__init__.py +20 -0
  639. platformforge/tokensave/budget.py +62 -0
  640. platformforge/tokensave/estimate.py +21 -0
  641. platformforge/tokensave/index.py +172 -0
  642. platformforge/tokensave/ledger.py +121 -0
  643. platformforge/tokensave/packs.py +285 -0
  644. platformforge/ui/__init__.py +28 -0
  645. platformforge/ui/app.py +465 -0
  646. platformforge/ui/home.py +113 -0
  647. platformforge/ui/i18n.py +143 -0
  648. platformforge/ui/kit.py +689 -0
  649. platformforge/ui/screen.py +628 -0
  650. platformforge/ui/tui.py +94 -0
  651. platformforge/ui/wizard.py +309 -0
  652. platformforge/workspace/__init__.py +13 -0
  653. platformforge/workspace/models.py +35 -0
  654. platformforge/workspace/service.py +69 -0
  655. platformforge-0.1.0.dist-info/METADATA +212 -0
  656. platformforge-0.1.0.dist-info/RECORD +659 -0
  657. platformforge-0.1.0.dist-info/WHEEL +4 -0
  658. platformforge-0.1.0.dist-info/entry_points.txt +3 -0
  659. platformforge-0.1.0.dist-info/licenses/LICENSE +21 -0
platformforge/_graphstudio.py ADDED
@@ -0,0 +1,376 @@
1
+ """Forge Graph Studio — local-first, read-only graph explorer.
2
+
3
+ A zero-dependency stdlib server (``http.server`` on 127.0.0.1) plus a
4
+ single-file HTML/canvas frontend embedded below. No Node, no CDN, no
5
+ build step — the whole app ships as Python package source.
6
+
7
+ GET-only by design: exploring a graph can never modify the project
8
+ (§4.4). ``serve()`` never opens a browser unless asked; ``--no-browser``
9
+ prints the URL for SSH port-forwarding.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import threading
16
+ import webbrowser
17
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ STUDIO_HTML = r"""<!doctype html>
22
+ <html lang="en">
23
+ <head>
24
+ <meta charset="utf-8">
25
+ <title>Forge Graph Studio</title>
26
+ <meta name="viewport" content="width=device-width,initial-scale=1">
27
+ <style>
28
+ :root{--bg:#0d1117;--panel:#161b22;--fg:#e6edf3;--dim:#8b949e;--line:#30363d;--acc:#58a6ff}
29
+ *{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);
30
+ font:13px/1.4 ui-monospace,Consolas,monospace;display:grid;
31
+ grid-template-columns:220px 1fr 280px;grid-template-rows:44px 1fr 26px;height:100vh}
32
+ header{grid-column:1/4;display:flex;gap:12px;align-items:center;padding:0 12px;
33
+ background:var(--panel);border-bottom:1px solid var(--line)}
34
+ header b{color:var(--acc)}select,input{background:var(--bg);color:var(--fg);
35
+ border:1px solid var(--line);border-radius:4px;padding:4px 6px}
36
+ #side,#insp{background:var(--panel);padding:10px;overflow:auto}
37
+ #side{border-right:1px solid var(--line)}#insp{border-left:1px solid var(--line)}
38
+ #wrap{position:relative;overflow:hidden}canvas{display:block;width:100%;height:100%;cursor:grab}
39
+ footer{grid-column:1/4;background:var(--panel);border-top:1px solid var(--line);
40
+ display:flex;gap:16px;padding:4px 12px;color:var(--dim)}
41
+ .k{word-break:break-all}.dim{color:var(--dim)}h4{margin:10px 0 4px;color:var(--dim);
42
+ text-transform:uppercase;font-size:11px;letter-spacing:.05em}
43
+ label.f{display:block;margin:2px 0;cursor:pointer}
44
+ #insp .pill{display:inline-block;border:1px solid var(--line);border-radius:10px;
45
+ padding:0 8px;margin:1px 2px;font-size:11px}
46
+ .ev{color:var(--acc);font-size:11px;word-break:break-all}
47
+ </style></head>
48
+ <body>
49
+ <header><b>FORGE GRAPH STUDIO</b>
50
+ <select id="gsel"></select>
51
+ <input id="q" placeholder="search…" size="20">
52
+ <span id="meta" class="dim"></span></header>
53
+ <div id="side"><h4>Layers</h4><div id="layers"></div>
54
+ <h4>Edge kinds</h4><div id="ekinds"></div>
55
+ <h4>Legend</h4><div id="legend" class="dim"></div></div>
56
+ <div id="wrap"><canvas id="cv"></canvas></div>
57
+ <div id="insp"><h4>Inspector</h4><div id="ibody" class="dim">select a node or edge</div></div>
58
+ <footer><span id="stats"></span><span id="prov"></span>
59
+ <span class="dim">scroll=zoom · drag=pan · click=inspect · n=neighbors ·
60
+ e=export · d=diff · s=snapshot · esc=reset</span></footer>
61
+ <script>
62
+ let G={nodes:[],edges:[]},L={},view={x:0,y:0,s:1},sel=null,hover=null,
63
+ kindsOn={},ekindsOn={},PAL={},running=true;
64
+ const cv=document.getElementById('cv'),cx=cv.getContext('2d');
65
+ const KCOLORS=['#58a6ff','#f78166','#7ee787','#ffa657','#d2a8ff','#76e3ea','#ff9bce','#e3b341'];
66
+ const ESTYLE={observed:[],declared:[6,3],inferred:[3,4],planned:[2,4],desired:[8,3],unknown:[1,5]};
67
+ function pal(k){if(!(k in PAL))PAL[k]=KCOLORS[Object.keys(PAL).length%KCOLORS.length];return PAL[k]}
68
+ async function loadGraphs(){const r=await fetch('/api/graphs');const d=await r.json();
69
+ const s=document.getElementById('gsel');s.innerHTML='';
70
+ d.graphs.forEach(g=>{const o=document.createElement('option');o.value=g.graph_id;
71
+ o.textContent=`${g.provider_id} · ${g.graph_id}`+
72
+ ` (${g.node_count}/${g.edge_count})`;s.appendChild(o)});
73
+ if(d.graphs.length)loadGraph(d.graphs[0].graph_id);
74
+ s.onchange=e=>loadGraph(e.target.value)}
75
+ async function loadGraph(id){const r=await fetch('/api/graph/'+encodeURIComponent(id));
76
+ const d=await r.json();sel=null;L={};
77
+ G.nodes=(d.nodes||[]).map(n=>({...n,x:Math.random()*600-300,y:Math.random()*600-300,vx:0,vy:0,deg:0}));
78
+ G.edges=(d.edges||[]);
79
+ const byId={};G.nodes.forEach(n=>{byId[n.id]=n});
80
+ G.edges.forEach(e=>{if(byId[e.source])byId[e.source].deg++;if(byId[e.target])byId[e.target].deg++});
81
+ G.edges=G.edges.filter(e=>byId[e.source]&&byId[e.target]);
82
+ kindsOn={};G.nodes.forEach(n=>kindsOn[n.kind]=true);
83
+ ekindsOn={};G.edges.forEach(e=>ekindsOn[e.kind]=true);
84
+ sidePanel();document.getElementById('meta').textContent=
85
+ `${d.descriptor.provider_id} · ${d.descriptor.domain} · ${d.descriptor.generated_at||''}`;
86
+ document.getElementById('prov').textContent=
87
+ (d.descriptor.limitations||[]).join(' | ').slice(0,120);
88
+ running=true;tick()}
89
+ function sidePanel(){const L=document.getElementById('layers'),E=document.getElementById('ekinds');
90
+ L.innerHTML='';E.innerHTML='';
91
+ Object.keys(kindsOn).sort().forEach(k=>{L.innerHTML+=
92
+ `<label class="f"><input type="checkbox" checked data-k="${k}">`+
93
+ ` <span style="color:${pal(k)}">●</span> ${k}</label>`});
94
+ Object.keys(ekindsOn).sort().forEach(k=>{E.innerHTML+=
95
+ `<label class="f"><input type="checkbox" checked data-ek="${k}"> ${k}</label>`});
96
+ L.querySelectorAll('input').forEach(i=>i.onchange=e=>{kindsOn[e.target.dataset.k]=e.target.checked});
97
+ E.querySelectorAll('input').forEach(i=>i.onchange=e=>{ekindsOn[e.target.dataset.ek]=e.target.checked});
98
+ document.getElementById('legend').innerHTML=
99
+ Object.keys(ESTYLE).map(s=>`<div>─ ${s}</div>`).join('')}
100
+ function tick(){let n=0;const byId={};G.nodes.forEach(x=>byId[x.id]=x);
101
+ for(let i=0;i<G.nodes.length;i++)for(let j=i+1;j<G.nodes.length;j++){
102
+ const a=G.nodes[i],b=G.nodes[j];let dx=a.x-b.x,dy=a.y-b.y,d=dx*dx+dy*dy+40;
103
+ const f=Math.min(2000/d,40);a.vx+=dx/d*f;a.vy+=dy/d*f;b.vx-=dx/d*f;b.vy-=dy/d*f}
104
+ G.edges.forEach(e=>{const a=byId[e.source],b=byId[e.target];
105
+ const dx=b.x-a.x,dy=b.y-a.y,d=Math.hypot(dx,dy)||1,f=(d-120)*0.02;
106
+ a.vx+=dx/d*f*d/120;a.vy+=dy/d*f*d/120;b.vx-=dx/d*f*d/120;b.vy-=dy/d*f*d/120});
107
+ G.nodes.forEach(a=>{a.vx-=a.x*0.001;a.vy-=a.y*0.001;a.vx*=0.85;a.vy*=0.85;
108
+ a.x+=a.vx;a.y+=a.vy;if(Math.abs(a.vx)+Math.abs(a.vy)>0.1)n++});
109
+ draw();if(n>0&&running)requestAnimationFrame(tick)}
110
+ function toS(x,y){const r=cv.getBoundingClientRect();
111
+ return[(x*view.s)+r.width/2+view.x,(y*view.s)+r.height/2+view.y]}
112
+ function draw(){const r=cv.getBoundingClientRect();
113
+ if(cv.width!==r.width*devicePixelRatio){cv.width=r.width*devicePixelRatio;
114
+ cv.height=r.height*devicePixelRatio}
115
+ cx.setTransform(devicePixelRatio,0,0,devicePixelRatio,0,0);
116
+ cx.clearRect(0,0,r.width,r.height);
117
+ const q=(document.getElementById('q').value||'').toLowerCase();
118
+ const vis={};let vc=0,ec=0;
119
+ G.nodes.forEach(n=>{const s=(n.label||'')+' '+n.id;
120
+ vis[n.id]=kindsOn[n.kind]&&(!q||s.toLowerCase().includes(q))&&
121
+ (!focusSet||focusSet.has(n.id));
122
+ if(vis[n.id])vc++});
123
+ G.edges.forEach(e=>{if(!vis[e.source]||!vis[e.target]||!ekindsOn[e.kind])return;ec++;
124
+ const a=G.nodes.find(n=>n.id===e.source),b=G.nodes.find(n=>n.id===e.target);
125
+ const[x1,y1]=toS(a.x,a.y),[x2,y2]=toS(b.x,b.y);
126
+ cx.strokeStyle=e===sel?'#f0f6fc':'#444c56';cx.lineWidth=e===sel?2:1;
127
+ cx.setLineDash(ESTYLE[e.epistemic_state]||ESTYLE.unknown);
128
+ cx.beginPath();cx.moveTo(x1,y1);cx.lineTo(x2,y2);cx.stroke();
129
+ // arrowhead
130
+ const an=Math.atan2(y2-y1,x2-x1);cx.setLineDash([]);cx.beginPath();
131
+ cx.moveTo(x2,y2);cx.lineTo(x2-8*Math.cos(an-0.5),y2-8*Math.sin(an-0.5));
132
+ cx.lineTo(x2-8*Math.cos(an+0.5),y2-8*Math.sin(an+0.5));cx.fillStyle=cx.strokeStyle;cx.fill()});
133
+ cx.setLineDash([]);
134
+ G.nodes.forEach(n=>{if(!vis[n.id])return;const[x,y]=toS(n.x,n.y);
135
+ const rad=4+Math.min(n.deg,12);
136
+ cx.beginPath();cx.arc(x,y,rad,0,7);
137
+ const dcol=drawDiffColors&&DC[drawDiffColors[n.id]];
138
+ cx.fillStyle=n===sel?'#f0f6fc':(n===hover?'#fff':(dcol||pal(n.kind)));cx.fill();
139
+ if(n===sel){cx.strokeStyle='#58a6ff';cx.lineWidth=2;cx.stroke()}
140
+ if(view.s>0.5||n.deg>4){cx.fillStyle='#8b949e';cx.font='10px monospace';
141
+ cx.fillText((n.label||n.id).slice(0,24),x+rad+2,y+3)}});
142
+ document.getElementById('stats').textContent=`${vc} nodes · ${ec} edges visible`}
143
+ cv.onwheel=e=>{e.preventDefault();const r=cv.getBoundingClientRect();
144
+ const mx=e.clientX-r.left-r.width/2,my=e.clientY-r.top-r.height/2;
145
+ const f=e.deltaY<0?1.15:0.87;view.x=(view.x-mx)*f+mx;view.y=(view.y-my)*f+my;
146
+ view.s*=f;draw()};
147
+ let drag=null;cv.onmousedown=e=>{const p=pick(e);drag={e,node:p.node,mx:view.x,my:view.y}};
148
+ cv.onmousemove=e=>{if(drag){const r=cv.getBoundingClientRect();
149
+ if(drag.node){drag.node.x=(e.clientX-r.left-r.width/2-view.x)/view.s;
150
+ drag.node.y=(e.clientY-r.top-r.height/2-view.y)/view.s}else{
151
+ view.x=drag.mx+e.clientX-drag.e.clientX;view.y=drag.my+e.clientY-drag.e.clientY}
152
+ draw()}else{const p=pick(e);hover=p.node;draw()}};
153
+ cv.onmouseup=e=>{const p=pick(e);
154
+ if(!drag||(Math.abs(e.clientX-drag.e.clientX)<4&&Math.abs(e.clientY-drag.e.clientY)<4)){
155
+ sel=p.node||p.edge||null;inspect()}
156
+ drag=null;draw()};
157
+ function pick(e){const r=cv.getBoundingClientRect();
158
+ const wx=(e.clientX-r.left-r.width/2-view.x)/view.s,
159
+ wy=(e.clientY-r.top-r.height/2-view.y)/view.s;
160
+ for(const n of G.nodes)if(Math.hypot(n.x-wx,n.y-wy)<12/view.s+4)return{node:n};
161
+ for(const ed of G.edges){const a=G.nodes.find(n=>n.id===ed.source),
162
+ b=G.nodes.find(n=>n.id===ed.target);if(!a||!b)continue;
163
+ const L2=(b.x-a.x)**2+(b.y-a.y)**2||1;
164
+ const t=Math.max(0,Math.min(1,((wx-a.x)*(b.x-a.x)+(wy-a.y)*(b.y-a.y))/L2));
165
+ if(Math.hypot(wx-(a.x+t*(b.x-a.x)),wy-(a.y+t*(b.y-a.y)))<6/view.s)return{edge:ed}}
166
+ return{}}
167
+ function inspect(){const b=document.getElementById('ibody');if(!sel){
168
+ b.innerHTML='<span class="dim">select a node or edge</span>';return}
169
+ let h='';
170
+ if(sel.kind&&sel.label!==undefined&&!sel.source){
171
+ h=`<div class="k"><b>${sel.label||sel.id}</b></div>
172
+ <span class="pill">${sel.kind}</span><span class="pill">${sel.epistemic_state}</span>
173
+ <span class="pill">${sel.source_provider||''}</span>
174
+ <h4>Attributes</h4><div class="k">${JSON.stringify(sel.attributes||{},null,1)}</div>
175
+ <h4>Evidence</h4>${(sel.evidence_refs||[]).map(e=>`<div class="ev">${e}</div>`)
176
+ .join('')||'<span class="dim">none</span>'}
177
+ <h4>Edges (${G.edges.filter(e=>e.source===sel.id||e.target===sel.id).length})</h4>`;
178
+ }else{h=`<div class="k"><b>${sel.kind}</b></div>
179
+ <div class="k dim">${sel.source} → ${sel.target}</div>
180
+ <span class="pill">${sel.epistemic_state}</span><span class="pill">${sel.provenance||''}</span>
181
+ ${sel.confidence!=null?`<span class="pill">conf ${sel.confidence}</span>`:''}
182
+ <h4>Evidence</h4>${(sel.evidence_refs||[]).map(e=>`<div class="ev">${e}</div>`)
183
+ .join('')||'<span class="dim">none</span>'}
184
+ <h4>Temporal</h4><div class="k">${Object.keys(sel.temporal||{}).length?
185
+ JSON.stringify(sel.temporal):'none'}</div>`}
186
+ b.innerHTML=h}
187
+ document.getElementById('q').oninput=draw;
188
+ // --- premium interactions (Cycle 4): neighbors / export / diff / snapshot ---
189
+ let focusSet=null; // BFS subgraph when 'n' pressed
190
+ function neighbors(seed){const adj={};G.edges.forEach(e=>{
191
+ (adj[e.source]=adj[e.source]||new Set()).add(e.target);
192
+ (adj[e.target]=adj[e.target]||new Set()).add(e.source)});
193
+ const seen=new Set([seed]);let fr=[seed];
194
+ for(let d=0;d<2&&fr.length;d++){const nx=[];fr.forEach(id=>{
195
+ (adj[id]||[]).forEach(m=>{if(!seen.has(m)){seen.add(m);nx.push(m)}})});fr=nx}
196
+ return seen}
197
+ async function exportVisible(){const q=(document.getElementById('q').value||'').toLowerCase();
198
+ const vis={};G.nodes.forEach(n=>{const s=(n.label||'')+' '+n.id;
199
+ vis[n.id]=kindsOn[n.kind]&&(!q||s.toLowerCase().includes(q))&&(!focusSet||focusSet.has(n.id))});
200
+ const doc={exported_at:new Date().toISOString(),
201
+ nodes:G.nodes.filter(n=>vis[n.id]).map(n=>({id:n.id,kind:n.kind,label:n.label,
202
+ epistemic_state:n.epistemic_state,attributes:n.attributes,evidence_refs:n.evidence_refs})),
203
+ edges:G.edges.filter(e=>vis[e.source]&&vis[e.target]&&ekindsOn[e.kind])};
204
+ const a=document.createElement('a');a.href=URL.createObjectURL(
205
+ new Blob([JSON.stringify(doc,null,1)],{type:'application/json'}));
206
+ a.download='forge-graph-subgraph.json';a.click()}
207
+ let diffRef=null;
208
+ async function diffMode(){const r=await fetch('/api/graphs');const d=await r.json();
209
+ if(d.graphs.length<2){document.getElementById('prov').textContent=
210
+ 'diff needs ≥2 graphs loaded';return}
211
+ const other=d.graphs.map(g=>g.graph_id).find(id=>id!==curId)||d.graphs[0].graph_id;
212
+ const rr=await fetch('/api/graph/'+encodeURIComponent(other));const o=await rr.json();
213
+ const on={};(o.nodes||[]).forEach(n=>on[n.id]=n);
214
+ const oe={};(o.edges||[]).forEach(e=>oe[e.source+'>'+e.target+':'+e.kind]=1);
215
+ const eadded=G.edges.filter(e=>!oe[e.source+'>'+e.target+':'+e.kind]).length;
216
+ let added=0,removed=0,changed=0;const cls={};
217
+ G.nodes.forEach(n=>{if(!on[n.id]){cls[n.id]='added';added++}else if(
218
+ JSON.stringify(on[n.id].attributes)!==JSON.stringify(n.attributes)||
219
+ on[n.id].epistemic_state!==n.epistemic_state){cls[n.id]='changed';changed++}else cls[n.id]='same'});
220
+ removed=(o.nodes||[]).filter(n=>!G.nodes.find(x=>x.id===n.id)).length;
221
+ diffRef={other,cls};
222
+ drawDiffColors=cls;
223
+ document.getElementById('prov').textContent=
224
+ `diff vs ${other}: +${added} ~${changed} −${removed} nodes · +${eadded} edges (esc clears)`;
225
+ draw()}
226
+ let drawDiffColors=null;
227
+ const DC={added:'#7ee787',removed:'#f78166',changed:'#ffa657',same:null};
228
+ let curId=null;
229
+ const _loadGraph=loadGraph;
230
+ loadGraph=async function(id){curId=id;diffRef=null;drawDiffColors=null;
231
+ await _loadGraph(id)}
232
+ function snapshotSave(){try{localStorage.setItem('forge-graph-snap',
233
+ JSON.stringify({graph:curId,view,q:document.getElementById('q').value,
234
+ kinds:kindsOn,ekinds:ekindsOn,when:Date.now()}));
235
+ document.getElementById('prov').textContent='snapshot saved (s restores)'}catch(e){}}
236
+ function snapshotLoad(){try{const s=JSON.parse(localStorage.getItem('forge-graph-snap')||'null');
237
+ if(!s)return;view=s.view;document.getElementById('q').value=s.q||'';
238
+ Object.assign(kindsOn,s.kinds||{});Object.assign(ekindsOn,s.ekinds||{});draw()}catch(e){}}
239
+ document.onkeydown=e=>{
240
+ if(e.key==='Escape'){view={x:0,y:0,s:1};sel=null;focusSet=null;diffRef=null;
241
+ drawDiffColors=null;inspect();draw()}
242
+ else if(e.key==='n'&&sel&&sel.id!==undefined){focusSet=focusSet?null:neighbors(sel.id);draw()}
243
+ else if(e.key==='e')exportVisible()
244
+ else if(e.key==='d')diffMode()
245
+ else if(e.key==='s'){localStorage.getItem('forge-graph-snap')?snapshotLoad():snapshotSave()}};
246
+ loadGraphs();
247
+ </script></body></html>
248
+ """
249
+
250
+
251
+ def _handler(views: dict[str, dict[str, Any]]) -> type[BaseHTTPRequestHandler]:
252
+ class StudioHandler(BaseHTTPRequestHandler):
253
+ def log_message(self, fmt: str, *args: object) -> None: # quiet
254
+ pass
255
+
256
+ def _send(self, code: int, body: bytes, ctype: str) -> None:
257
+ self.send_response(code)
258
+ self.send_header("Content-Type", ctype)
259
+ self.send_header("Content-Length", str(len(body)))
260
+ self.send_header("Cache-Control", "no-store")
261
+ self.end_headers()
262
+ self.wfile.write(body)
263
+
264
+ def _json(self, code: int, doc: object) -> None:
265
+ self._send(code, json.dumps(doc, default=str).encode(), "application/json")
266
+
267
+ def do_GET(self) -> None: # noqa: N802 - stdlib naming
268
+ path = self.path.split("?")[0].rstrip("/") or "/"
269
+ if path == "/":
270
+ self._send(200, STUDIO_HTML.encode(), "text/html; charset=utf-8")
271
+ return
272
+ if path == "/api/health":
273
+ self._json(200, {"status": "ok", "graphs": len(views)})
274
+ return
275
+ if path == "/api/graphs":
276
+ self._json(200, {"graphs": [v["descriptor"] for v in views.values()]})
277
+ return
278
+ if path.startswith("/api/graph/"):
279
+ gid = path[len("/api/graph/"):]
280
+ view = views.get(gid)
281
+ if view is None:
282
+ self._json(404, {"error": f"unknown graph {gid!r}"})
283
+ return
284
+ self._json(200, view)
285
+ return
286
+ self._json(404, {"error": "not found"})
287
+
288
+ def do_POST(self) -> None: # read-only by design (§4.4)
289
+ self._json(405, {"error": "Graph Studio is read-only"})
290
+
291
+ do_PUT = do_DELETE = do_PATCH = do_POST
292
+
293
+ return StudioHandler
294
+
295
+
296
+ def serve(
297
+ views: list[dict[str, Any]],
298
+ *,
299
+ host: str = "127.0.0.1",
300
+ port: int = 0,
301
+ open_browser: bool = True,
302
+ out: Any = None,
303
+ ) -> int:
304
+ """Serve the studio until Ctrl+C. ``views`` are ForgeGraphView dicts.
305
+
306
+ Binds loopback only — never exposes graphs on the network. With
307
+ ``open_browser=False`` (``--no-browser``, remote/SSH) the URL is
308
+ printed for port-forwarding instead.
309
+ """
310
+ out = out or __import__("sys").stdout
311
+ by_id = {v["descriptor"]["graph_id"]: v for v in views}
312
+ httpd = ThreadingHTTPServer((host, port), _handler(by_id))
313
+ bound = httpd.server_address[1]
314
+ url = f"http://{host}:{bound}/"
315
+ if open_browser:
316
+ threading.Timer(0.3, lambda: webbrowser.open(url)).start()
317
+ print(f"Graph Studio → {url} (Ctrl+C to stop)", file=out)
318
+ else:
319
+ print(f"Graph Studio listening on {url}", file=out)
320
+ print(f" remote? forward with: ssh -L {bound}:127.0.0.1:{bound} <host>", file=out)
321
+ try:
322
+ httpd.serve_forever()
323
+ except KeyboardInterrupt:
324
+ pass
325
+ finally:
326
+ httpd.server_close()
327
+ return 0
328
+
329
+
330
+ def graph_studio_enabled(
331
+ root: Path | str | None = None,
332
+ *,
333
+ state_rel: str = ".forge/install",
334
+ user_state_rel: str = "~/.forge/install",
335
+ ) -> bool:
336
+ """Was Graph Studio declined at install time?
337
+
338
+ ``components.json`` under the forge's state dir records the optional-
339
+ component selection (``graph_studio: false``). Absence means the
340
+ default — enabled — so checkouts and pre-component installs keep
341
+ working.
342
+ """
343
+ import json
344
+
345
+ candidates: list[Path] = []
346
+ if root:
347
+ candidates.append(Path(root) / state_rel / "components.json")
348
+ candidates.append(Path(user_state_rel).expanduser() / "components.json")
349
+ for p in candidates:
350
+ if not p.is_file():
351
+ continue
352
+ try:
353
+ doc = json.loads(p.read_text(encoding="utf-8"))
354
+ except Exception:
355
+ continue
356
+ if "graph_studio" in doc:
357
+ return bool(doc["graph_studio"])
358
+ return True
359
+
360
+
361
+ def open_studio(
362
+ views: list[Any],
363
+ *,
364
+ open_browser: bool = True,
365
+ port: int = 0,
366
+ out: Any = None,
367
+ ) -> int:
368
+ """Entry for ``graph ui``: accept views or view objects, then serve."""
369
+ docs = [v.to_dict() if hasattr(v, "to_dict") else v for v in views]
370
+ if not docs:
371
+ print(
372
+ "no graphs available — produce one first (see `graph build`/`graph` docs)",
373
+ file=out,
374
+ )
375
+ return 2
376
+ return serve(docs, open_browser=open_browser, port=port, out=out)
platformforge/_graphview.py ADDED
@@ -0,0 +1,181 @@
1
+ """ForgeGraphView/v1 — the visualization contract for Graph Studio.
2
+
3
+ A read-only, rendering-ready projection of a forge's real graph. The
4
+ graph engines stay authoritative; this contract only *carries* their
5
+ data to a viewer without losing provenance, epistemic state or evidence
6
+ references. Layout coordinates are deliberately absent — they belong to
7
+ the visualization layer, not the model.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import time
13
+ import uuid
14
+ from dataclasses import asdict, dataclass, field
15
+ from typing import Any
16
+
17
+ GRAPHVIEW_SCHEMA = "forge/ForgeGraphView/v1"
18
+ GRAPH_DESCRIPTOR_SCHEMA = "forge/GraphDescriptor/v1"
19
+
20
+ # Epistemic states a view may carry. Engines map their own vocabulary
21
+ # onto these explicitly; unmapped states stay "unknown", never upgraded.
22
+ EPISTEMIC_STATES = (
23
+ "observed",
24
+ "declared",
25
+ "planned",
26
+ "desired",
27
+ "inferred",
28
+ "unknown",
29
+ )
30
+
31
+ # Capabilities an adapter may declare — only real ones.
32
+ GRAPH_CAPABILITIES = (
33
+ "snapshots",
34
+ "node_inspect",
35
+ "edge_inspect",
36
+ "neighbors",
37
+ "paths",
38
+ "dependency_traversal",
39
+ "impact_analysis",
40
+ "snapshot_diff",
41
+ "temporal",
42
+ "search",
43
+ "filter",
44
+ "export",
45
+ )
46
+
47
+
48
+ # Engine vocabulary → view vocabulary (explicit, reversible): a state an
49
+ # engine uses that has a view equivalent is translated; anything else
50
+ # stays "unknown" — never silently upgraded to observed/declared.
51
+ EPISTEMIC_TRANSLATION = {
52
+ "explicit": "declared",
53
+ "asserted": "declared",
54
+ "actual": "observed",
55
+ }
56
+
57
+
58
+ def _check(state: str) -> str:
59
+ if state in EPISTEMIC_STATES:
60
+ return state
61
+ return EPISTEMIC_TRANSLATION.get(state, "unknown")
62
+
63
+
64
+ @dataclass(frozen=True, kw_only=True)
65
+ class GraphDescriptor:
66
+ """Summary of one graph a provider can expose (§1.2)."""
67
+
68
+ graph_id: str
69
+ provider_id: str
70
+ domain: str
71
+ graph_schema: str = GRAPH_DESCRIPTOR_SCHEMA
72
+ snapshot_id: str = ""
73
+ generated_at: str = ""
74
+ node_count: int = 0
75
+ edge_count: int = 0
76
+ available_layers: tuple[str, ...] = ()
77
+ available_queries: tuple[str, ...] = ()
78
+ capabilities: tuple[str, ...] = ()
79
+ limitations: tuple[str, ...] = ()
80
+
81
+ def to_dict(self) -> dict[str, Any]:
82
+ return asdict(self)
83
+
84
+
85
+ @dataclass(frozen=True, kw_only=True)
86
+ class GraphNodeView:
87
+ """One node, with engine provenance preserved (§1.3)."""
88
+
89
+ id: str
90
+ kind: str
91
+ label: str
92
+ domain: str = ""
93
+ source_provider: str = ""
94
+ attributes: dict[str, Any] = field(default_factory=dict)
95
+ epistemic_state: str = "unknown"
96
+ evidence_refs: tuple[str, ...] = ()
97
+ snapshot_ref: str = ""
98
+
99
+ def __post_init__(self) -> None:
100
+ object.__setattr__(self, "epistemic_state", _check(self.epistemic_state))
101
+
102
+ def to_dict(self) -> dict[str, Any]:
103
+ return asdict(self)
104
+
105
+
106
+ @dataclass(frozen=True, kw_only=True)
107
+ class GraphEdgeView:
108
+ """One directed edge; direction and semantics preserved (§1.4)."""
109
+
110
+ id: str
111
+ source: str
112
+ target: str
113
+ kind: str
114
+ direction: str = "directed"
115
+ provenance: str = "unknown"
116
+ epistemic_state: str = "unknown"
117
+ evidence_refs: tuple[str, ...] = ()
118
+ confidence: float | None = None
119
+ temporal: dict[str, Any] = field(default_factory=dict)
120
+ attributes: dict[str, Any] = field(default_factory=dict)
121
+
122
+ def __post_init__(self) -> None:
123
+ object.__setattr__(self, "epistemic_state", _check(self.epistemic_state))
124
+
125
+ def to_dict(self) -> dict[str, Any]:
126
+ d = asdict(self)
127
+ if self.confidence is None:
128
+ d.pop("confidence")
129
+ return d
130
+
131
+
132
+ @dataclass(frozen=True, kw_only=True)
133
+ class ForgeGraphView:
134
+ """A complete view document: descriptor + nodes + edges."""
135
+
136
+ descriptor: GraphDescriptor
137
+ nodes: tuple[GraphNodeView, ...] = ()
138
+ edges: tuple[GraphEdgeView, ...] = ()
139
+ schema: str = GRAPHVIEW_SCHEMA
140
+
141
+ def to_dict(self) -> dict[str, Any]:
142
+ return {
143
+ "schema": self.schema,
144
+ "descriptor": self.descriptor.to_dict(),
145
+ "nodes": [n.to_dict() for n in self.nodes],
146
+ "edges": [e.to_dict() for e in self.edges],
147
+ }
148
+
149
+ @staticmethod
150
+ def from_dict(doc: dict[str, Any]) -> ForgeGraphView:
151
+ d = doc["descriptor"]
152
+ descriptor = GraphDescriptor(
153
+ **{k: tuple(v) if isinstance(v, list) else v for k, v in d.items()}
154
+ )
155
+ nodes = tuple(
156
+ GraphNodeView(
157
+ **{k: tuple(v) if isinstance(v, list) else v for k, v in n.items()}
158
+ )
159
+ for n in doc.get("nodes", [])
160
+ )
161
+ edges = tuple(
162
+ GraphEdgeView(
163
+ **{k: tuple(v) if isinstance(v, list) else v for k, v in e.items()}
164
+ )
165
+ for e in doc.get("edges", [])
166
+ )
167
+ return ForgeGraphView(descriptor=descriptor, nodes=nodes, edges=edges)
168
+
169
+
170
+ def new_descriptor(*, provider_id: str, domain: str, graph_id: str | None = None,
171
+ capabilities: tuple[str, ...] = (),
172
+ limitations: tuple[str, ...] = ()) -> GraphDescriptor:
173
+ """A descriptor with real provenance stamps."""
174
+ return GraphDescriptor(
175
+ graph_id=graph_id or f"graph-{uuid.uuid4().hex[:8]}",
176
+ provider_id=provider_id,
177
+ domain=domain,
178
+ generated_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
179
+ capabilities=tuple(c for c in capabilities if c in GRAPH_CAPABILITIES),
180
+ limitations=limitations,
181
+ )