gebra 0.0.1__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 (112) hide show
  1. gebra/__init__.py +114 -0
  2. gebra/annotations/__init__.py +154 -0
  3. gebra/annotations/contract.py +1036 -0
  4. gebra/annotations/errors.py +93 -0
  5. gebra/annotations/inference.py +1426 -0
  6. gebra/annotations/resolve.py +676 -0
  7. gebra/annotations/sidecar.py +776 -0
  8. gebra/annotations/slots.py +105 -0
  9. gebra/audit/__init__.py +79 -0
  10. gebra/audit/export.py +332 -0
  11. gebra/audit/freshness.py +128 -0
  12. gebra/audit/models.py +258 -0
  13. gebra/cli/__init__.py +47 -0
  14. gebra/cli/__main__.py +8 -0
  15. gebra/cli/app.py +681 -0
  16. gebra/cli/common.py +148 -0
  17. gebra/cli/diff.py +556 -0
  18. gebra/cli/display.py +307 -0
  19. gebra/cli/history.py +353 -0
  20. gebra/cli/invocation.py +192 -0
  21. gebra/cli/render.py +126 -0
  22. gebra/cli/resolve.py +378 -0
  23. gebra/cli/snapshot.py +343 -0
  24. gebra/cli/verify.py +357 -0
  25. gebra/diff/__init__.py +118 -0
  26. gebra/diff/contracts.py +375 -0
  27. gebra/diff/graph.py +190 -0
  28. gebra/diff/models.py +338 -0
  29. gebra/diff/state.py +260 -0
  30. gebra/diff/topology.py +367 -0
  31. gebra/diff/workflow.py +220 -0
  32. gebra/display/__init__.py +26 -0
  33. gebra/display/mermaid.py +240 -0
  34. gebra/display/overlay.py +349 -0
  35. gebra/extraction/__init__.py +231 -0
  36. gebra/extraction/base.py +83 -0
  37. gebra/extraction/builder.py +1229 -0
  38. gebra/extraction/compat.py +392 -0
  39. gebra/extraction/compiled.py +1330 -0
  40. gebra/extraction/contracts.py +616 -0
  41. gebra/extraction/digests.py +813 -0
  42. gebra/extraction/dispatch.py +320 -0
  43. gebra/extraction/envelope.py +297 -0
  44. gebra/extraction/errors.py +127 -0
  45. gebra/extraction/inference.py +82 -0
  46. gebra/extraction/lcel.py +1192 -0
  47. gebra/extraction/routing.py +309 -0
  48. gebra/extraction/sidecar.py +104 -0
  49. gebra/extraction/state.py +693 -0
  50. gebra/extraction/stock.py +121 -0
  51. gebra/extraction/warnings.py +368 -0
  52. gebra/ir/__init__.py +181 -0
  53. gebra/ir/base.py +59 -0
  54. gebra/ir/canonical.py +791 -0
  55. gebra/ir/identity.py +590 -0
  56. gebra/ir/models.py +515 -0
  57. gebra/ir/serialization.py +617 -0
  58. gebra/lineage/__init__.py +72 -0
  59. gebra/lineage/document.py +138 -0
  60. gebra/lineage/engine.py +265 -0
  61. gebra/lineage/models.py +244 -0
  62. gebra/naming.py +84 -0
  63. gebra/py.typed +0 -0
  64. gebra/pytest_plugin.py +2279 -0
  65. gebra/report/__init__.py +164 -0
  66. gebra/report/anchors.py +300 -0
  67. gebra/report/evidence.py +373 -0
  68. gebra/report/findings.py +149 -0
  69. gebra/report/human.py +465 -0
  70. gebra/report/native.py +38 -0
  71. gebra/report/rules.py +293 -0
  72. gebra/report/sarif.py +257 -0
  73. gebra/report/suggestions.py +82 -0
  74. gebra/snapshot/__init__.py +72 -0
  75. gebra/snapshot/engine.py +524 -0
  76. gebra/snapshot/models.py +164 -0
  77. gebra/store/__init__.py +121 -0
  78. gebra/store/atomic.py +124 -0
  79. gebra/store/base.py +63 -0
  80. gebra/store/models.py +361 -0
  81. gebra/store/serialization.py +198 -0
  82. gebra/store/store.py +507 -0
  83. gebra/testing/__init__.py +122 -0
  84. gebra/testing/fixtures.py +808 -0
  85. gebra/testing/harness.py +894 -0
  86. gebra/testing/mutations.py +2172 -0
  87. gebra/testing/strategies.py +1027 -0
  88. gebra/verify/__init__.py +422 -0
  89. gebra/verify/base.py +358 -0
  90. gebra/verify/conditions.py +741 -0
  91. gebra/verify/graph.py +898 -0
  92. gebra/verify/guards.py +657 -0
  93. gebra/verify/locations.py +245 -0
  94. gebra/verify/properties/__init__.py +37 -0
  95. gebra/verify/properties/dataflow_completeness.py +673 -0
  96. gebra/verify/properties/determinism_replay.py +334 -0
  97. gebra/verify/properties/effect_safety.py +489 -0
  98. gebra/verify/properties/graph_well_formed.py +351 -0
  99. gebra/verify/properties/termination_witness.py +1023 -0
  100. gebra/verify/registry.py +477 -0
  101. gebra/verify/report.py +242 -0
  102. gebra/verify/run.py +863 -0
  103. gebra/verify/witnesses.py +430 -0
  104. gebra/versioning/__init__.py +85 -0
  105. gebra/versioning/classify.py +289 -0
  106. gebra/versioning/models.py +301 -0
  107. gebra-0.0.1.dist-info/METADATA +453 -0
  108. gebra-0.0.1.dist-info/RECORD +112 -0
  109. gebra-0.0.1.dist-info/WHEEL +4 -0
  110. gebra-0.0.1.dist-info/entry_points.txt +5 -0
  111. gebra-0.0.1.dist-info/licenses/LICENSE +201 -0
  112. gebra-0.0.1.dist-info/licenses/NOTICE +2 -0
gebra/__init__.py ADDED
@@ -0,0 +1,114 @@
1
+ """gebra — design-time verification and versioning for LangGraph agent workflows.
2
+
3
+ gebra introspects an existing LangGraph ``StateGraph``, ``CompiledStateGraph``,
4
+ or LCEL ``Runnable`` — without ever invoking user code — and emits the frozen
5
+ Gebra IR (``ir_version`` 1.0); property validators verify that IR and return
6
+ structured witnesses or failures; and content-addressed snapshots with
7
+ structural diffs (V.S.F.E) record how workflow definitions evolve. gebra
8
+ verifies definitions; LangGraph runs them. Normative authority for every
9
+ contract implemented in this package: the frozen project specifications
10
+ (IR-SPEC, INTROSPECTION-SPEC, ANNOTATION-API-SPEC, PROPERTY-CATALOG-SPEC,
11
+ TERMINATION-WITNESS-SPEC, VERSION-COMPAT).
12
+
13
+ Two surfaces are exported from this module directly, because the specs spell
14
+ them at the top level: ``gebra.extract(workflow)`` (INTROSPECTION-SPEC §2) and
15
+ the ``@gebra.contract`` decorator family with its ``GebraContractError``
16
+ (ANNOTATION-API-SPEC §1). Both are resolved lazily (PEP 562) rather than
17
+ imported here, and the laziness is load-bearing rather than tidy:
18
+ :mod:`gebra.extraction` reads the substrate's classes to dispatch on them,
19
+ while the validator lane and the fixture-load path are proven — in a guarded
20
+ interpreter, by ``tests/verify/test_base.py`` and
21
+ ``tests/testing/test_hermeticity.py`` — to reach no langgraph import at all.
22
+ Importing the extractor here would put langgraph in the closure of ``import
23
+ gebra``, and with it in the closure of everything that imports anything from
24
+ this package. The decorators resolve out of :mod:`gebra.annotations` for the
25
+ same reason, one step further: annotating a node function must not drag in
26
+ either the substrate or the extractor. Everything else lives in its
27
+ subpackage: :mod:`gebra.ir`, :mod:`gebra.verify`, :mod:`gebra.extraction`,
28
+ :mod:`gebra.annotations`, :mod:`gebra.store`, :mod:`gebra.versioning`,
29
+ :mod:`gebra.diff`, :mod:`gebra.snapshot`, :mod:`gebra.lineage`,
30
+ :mod:`gebra.audit`, :mod:`gebra.testing`. Of those, :mod:`gebra.snapshot` is
31
+ the one that imports the extractor — it is the wiring from a live workflow to a
32
+ stored snapshot — so importing it imports the substrate, while the store,
33
+ version, diff, lineage and audit engines stay free of it.
34
+ """
35
+
36
+ from typing import TYPE_CHECKING, Any, Final
37
+
38
+ if TYPE_CHECKING: # resolved for type checkers only; at runtime `__getattr__` does it
39
+ from gebra.annotations import (
40
+ GebraContractError,
41
+ compensation,
42
+ contract,
43
+ deterministic,
44
+ effect,
45
+ idempotent,
46
+ pure,
47
+ variant,
48
+ )
49
+ from gebra.extraction import ExtractionError, extract
50
+
51
+ __version__ = "0.0.1"
52
+
53
+ __all__ = [
54
+ "ExtractionError",
55
+ "GebraContractError",
56
+ "compensation",
57
+ "contract",
58
+ "deterministic",
59
+ "effect",
60
+ "extract",
61
+ "idempotent",
62
+ "pure",
63
+ "variant",
64
+ ]
65
+
66
+ #: The names :func:`__getattr__` resolves out of :mod:`gebra.extraction`.
67
+ _EXTRACTION_EXPORTS: Final[frozenset[str]] = frozenset({"ExtractionError", "extract"})
68
+
69
+ #: The names it resolves out of :mod:`gebra.annotations`. The split is the point: touching a
70
+ #: decorator must not import the extractor, and with it the substrate.
71
+ _ANNOTATION_EXPORTS: Final[frozenset[str]] = frozenset(
72
+ {
73
+ "GebraContractError",
74
+ "compensation",
75
+ "contract",
76
+ "deterministic",
77
+ "effect",
78
+ "idempotent",
79
+ "pure",
80
+ "variant",
81
+ }
82
+ )
83
+
84
+ #: Every lazy export, for :func:`__dir__` and for the membership test.
85
+ _LAZY_EXPORTS: Final[frozenset[str]] = _EXTRACTION_EXPORTS | _ANNOTATION_EXPORTS
86
+
87
+
88
+ def __getattr__(name: str) -> Any:
89
+ """Resolve an entry point out of its subpackage on first access (PEP 562).
90
+
91
+ Written as two literal imports rather than a name→module table so that neither branch
92
+ reaches ``importlib``: this module is in the closure of every hermeticity tripwire in the
93
+ suite, and those scan for a dynamic-import primitive as well as running one.
94
+
95
+ Raises:
96
+ AttributeError: for every other name, as attribute access normally would.
97
+ """
98
+ if name in _EXTRACTION_EXPORTS:
99
+ import gebra.extraction
100
+
101
+ value = getattr(gebra.extraction, name)
102
+ elif name in _ANNOTATION_EXPORTS:
103
+ import gebra.annotations
104
+
105
+ value = getattr(gebra.annotations, name)
106
+ else:
107
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
108
+ globals()[name] = value # bind it, so the import happens once
109
+ return value
110
+
111
+
112
+ def __dir__() -> list[str]:
113
+ """List the lazy exports alongside what is already bound (PEP 562)."""
114
+ return sorted(set(globals()) | _LAZY_EXPORTS)
@@ -0,0 +1,154 @@
1
+ """The contract-declaration surface — ANNOTATION-API-SPEC.
2
+
3
+ How an author tells gebra what a node does. The spec gives the surface four parts, and this
4
+ package is where they land::
5
+
6
+ from gebra import contract, pure, effect, idempotent, deterministic, variant, compensation
7
+
8
+ * **§1 — decorators.** ``@gebra.contract`` and its six shorthands attach a
9
+ :class:`~gebra.annotations.contract.NodeContract` under ``__gebra_contract__`` and return
10
+ the decorated callable unchanged. Four consistency rules raise
11
+ :class:`~gebra.annotations.errors.GebraContractError` at import time.
12
+ * **§2 — the ``gebra.toml`` sidecar.** :mod:`gebra.annotations.sidecar` finds the file (an
13
+ explicit ``gebra.extract(workflow, sidecar=…)`` argument, else the nearest ``gebra.toml``
14
+ walking from the CWD to the repository root), parses it, and validates it — all of it
15
+ warning-grade, because "the sidecar is config and extraction stays total".
16
+ * **§4 — shallow inference.** :mod:`gebra.annotations.inference` reads a node callable's own
17
+ AST and applies the closed DEC-08 pattern table — ``input`` and ``output`` only — falling
18
+ to the decision D-011 conservative defaults with a finding that says why. It never yields
19
+ ``idempotent``, ``deterministic``, ``variant``, ``compensation`` or ``args_schema``, and it
20
+ evaluates nothing.
21
+ * **§3 — the per-slot precedence chain.** :mod:`gebra.annotations.resolve` runs the strict
22
+ Decorator > Tool-carried > Sidecar > Inference order per slot, reports a lower tier that
23
+ disagrees with an ``annotation-conflict`` (identical values, decided by byte-equality of
24
+ their ledger §6 canonicalizations, are not a disagreement), and validates the *resolved*
25
+ contract against the §1 invariants — all of it warning-grade, because extraction stays
26
+ total. Which live object supplies each tier is the extractor's question, and
27
+ :mod:`gebra.extraction.contracts` answers it.
28
+
29
+ **This package never imports the substrate,** and the direction is deliberate rather than
30
+ incidental: :mod:`gebra.extraction` imports langgraph to dispatch on its classes, and the
31
+ resolution step makes it a consumer of this package. Keeping the dependency one-way is
32
+ what lets ``import gebra`` — and a module that only decorates its node functions — stay free
33
+ of both the substrate and the extractor.
34
+
35
+ Nothing here imports langgraph, opens a socket, or executes anything (WA-07).
36
+ """
37
+
38
+ from gebra.annotations.contract import (
39
+ CONTRACT_ATTRIBUTE,
40
+ SLOT_KEYWORDS,
41
+ NodeContract,
42
+ compensation,
43
+ contract,
44
+ deterministic,
45
+ effect,
46
+ idempotent,
47
+ pure,
48
+ read_contract,
49
+ variant,
50
+ )
51
+ from gebra.annotations.errors import ContractErrorReason, GebraContractError
52
+ from gebra.annotations.inference import (
53
+ DEFAULT_EFFECT,
54
+ INFERENCE_SLOTS,
55
+ NEVER_INFERRED,
56
+ Blocker,
57
+ DefaultRule,
58
+ Inference,
59
+ InferenceFinding,
60
+ InferredKey,
61
+ NodeSource,
62
+ Pattern,
63
+ SourceCache,
64
+ SourceRule,
65
+ StateSchema,
66
+ infer,
67
+ infer_node,
68
+ read_node_source,
69
+ )
70
+ from gebra.annotations.resolve import (
71
+ IDENTIFIER_SLOTS,
72
+ PRECEDENCE,
73
+ TIER_SLOTS,
74
+ Contribution,
75
+ IssueKind,
76
+ Resolution,
77
+ ResolutionIssue,
78
+ ResolutionRule,
79
+ Surface,
80
+ carriable,
81
+ resolve,
82
+ slot_bytes,
83
+ slot_data,
84
+ )
85
+ from gebra.annotations.sidecar import (
86
+ SIDECAR_FILENAME,
87
+ SIDECAR_SCHEMA,
88
+ SidecarIssue,
89
+ SidecarReading,
90
+ SidecarRule,
91
+ SidecarSource,
92
+ discover_sidecar,
93
+ read_sidecar,
94
+ repository_root,
95
+ )
96
+ from gebra.annotations.slots import ANNOTATION_SLOTS, EFFECT_TAGS, AnnotationSlot, SlotGrade
97
+
98
+ __all__ = [
99
+ "ANNOTATION_SLOTS",
100
+ "CONTRACT_ATTRIBUTE",
101
+ "DEFAULT_EFFECT",
102
+ "EFFECT_TAGS",
103
+ "IDENTIFIER_SLOTS",
104
+ "INFERENCE_SLOTS",
105
+ "NEVER_INFERRED",
106
+ "PRECEDENCE",
107
+ "SIDECAR_FILENAME",
108
+ "SIDECAR_SCHEMA",
109
+ "SLOT_KEYWORDS",
110
+ "TIER_SLOTS",
111
+ "AnnotationSlot",
112
+ "Blocker",
113
+ "ContractErrorReason",
114
+ "Contribution",
115
+ "DefaultRule",
116
+ "GebraContractError",
117
+ "Inference",
118
+ "InferenceFinding",
119
+ "InferredKey",
120
+ "IssueKind",
121
+ "NodeContract",
122
+ "NodeSource",
123
+ "Pattern",
124
+ "Resolution",
125
+ "ResolutionIssue",
126
+ "ResolutionRule",
127
+ "SidecarIssue",
128
+ "SidecarReading",
129
+ "SidecarRule",
130
+ "SidecarSource",
131
+ "SlotGrade",
132
+ "SourceCache",
133
+ "SourceRule",
134
+ "StateSchema",
135
+ "Surface",
136
+ "carriable",
137
+ "compensation",
138
+ "contract",
139
+ "deterministic",
140
+ "discover_sidecar",
141
+ "effect",
142
+ "idempotent",
143
+ "infer",
144
+ "infer_node",
145
+ "pure",
146
+ "read_contract",
147
+ "read_node_source",
148
+ "read_sidecar",
149
+ "repository_root",
150
+ "resolve",
151
+ "slot_bytes",
152
+ "slot_data",
153
+ "variant",
154
+ ]