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.
- gebra/__init__.py +114 -0
- gebra/annotations/__init__.py +154 -0
- gebra/annotations/contract.py +1036 -0
- gebra/annotations/errors.py +93 -0
- gebra/annotations/inference.py +1426 -0
- gebra/annotations/resolve.py +676 -0
- gebra/annotations/sidecar.py +776 -0
- gebra/annotations/slots.py +105 -0
- gebra/audit/__init__.py +79 -0
- gebra/audit/export.py +332 -0
- gebra/audit/freshness.py +128 -0
- gebra/audit/models.py +258 -0
- gebra/cli/__init__.py +47 -0
- gebra/cli/__main__.py +8 -0
- gebra/cli/app.py +681 -0
- gebra/cli/common.py +148 -0
- gebra/cli/diff.py +556 -0
- gebra/cli/display.py +307 -0
- gebra/cli/history.py +353 -0
- gebra/cli/invocation.py +192 -0
- gebra/cli/render.py +126 -0
- gebra/cli/resolve.py +378 -0
- gebra/cli/snapshot.py +343 -0
- gebra/cli/verify.py +357 -0
- gebra/diff/__init__.py +118 -0
- gebra/diff/contracts.py +375 -0
- gebra/diff/graph.py +190 -0
- gebra/diff/models.py +338 -0
- gebra/diff/state.py +260 -0
- gebra/diff/topology.py +367 -0
- gebra/diff/workflow.py +220 -0
- gebra/display/__init__.py +26 -0
- gebra/display/mermaid.py +240 -0
- gebra/display/overlay.py +349 -0
- gebra/extraction/__init__.py +231 -0
- gebra/extraction/base.py +83 -0
- gebra/extraction/builder.py +1229 -0
- gebra/extraction/compat.py +392 -0
- gebra/extraction/compiled.py +1330 -0
- gebra/extraction/contracts.py +616 -0
- gebra/extraction/digests.py +813 -0
- gebra/extraction/dispatch.py +320 -0
- gebra/extraction/envelope.py +297 -0
- gebra/extraction/errors.py +127 -0
- gebra/extraction/inference.py +82 -0
- gebra/extraction/lcel.py +1192 -0
- gebra/extraction/routing.py +309 -0
- gebra/extraction/sidecar.py +104 -0
- gebra/extraction/state.py +693 -0
- gebra/extraction/stock.py +121 -0
- gebra/extraction/warnings.py +368 -0
- gebra/ir/__init__.py +181 -0
- gebra/ir/base.py +59 -0
- gebra/ir/canonical.py +791 -0
- gebra/ir/identity.py +590 -0
- gebra/ir/models.py +515 -0
- gebra/ir/serialization.py +617 -0
- gebra/lineage/__init__.py +72 -0
- gebra/lineage/document.py +138 -0
- gebra/lineage/engine.py +265 -0
- gebra/lineage/models.py +244 -0
- gebra/naming.py +84 -0
- gebra/py.typed +0 -0
- gebra/pytest_plugin.py +2279 -0
- gebra/report/__init__.py +164 -0
- gebra/report/anchors.py +300 -0
- gebra/report/evidence.py +373 -0
- gebra/report/findings.py +149 -0
- gebra/report/human.py +465 -0
- gebra/report/native.py +38 -0
- gebra/report/rules.py +293 -0
- gebra/report/sarif.py +257 -0
- gebra/report/suggestions.py +82 -0
- gebra/snapshot/__init__.py +72 -0
- gebra/snapshot/engine.py +524 -0
- gebra/snapshot/models.py +164 -0
- gebra/store/__init__.py +121 -0
- gebra/store/atomic.py +124 -0
- gebra/store/base.py +63 -0
- gebra/store/models.py +361 -0
- gebra/store/serialization.py +198 -0
- gebra/store/store.py +507 -0
- gebra/testing/__init__.py +122 -0
- gebra/testing/fixtures.py +808 -0
- gebra/testing/harness.py +894 -0
- gebra/testing/mutations.py +2172 -0
- gebra/testing/strategies.py +1027 -0
- gebra/verify/__init__.py +422 -0
- gebra/verify/base.py +358 -0
- gebra/verify/conditions.py +741 -0
- gebra/verify/graph.py +898 -0
- gebra/verify/guards.py +657 -0
- gebra/verify/locations.py +245 -0
- gebra/verify/properties/__init__.py +37 -0
- gebra/verify/properties/dataflow_completeness.py +673 -0
- gebra/verify/properties/determinism_replay.py +334 -0
- gebra/verify/properties/effect_safety.py +489 -0
- gebra/verify/properties/graph_well_formed.py +351 -0
- gebra/verify/properties/termination_witness.py +1023 -0
- gebra/verify/registry.py +477 -0
- gebra/verify/report.py +242 -0
- gebra/verify/run.py +863 -0
- gebra/verify/witnesses.py +430 -0
- gebra/versioning/__init__.py +85 -0
- gebra/versioning/classify.py +289 -0
- gebra/versioning/models.py +301 -0
- gebra-0.0.1.dist-info/METADATA +453 -0
- gebra-0.0.1.dist-info/RECORD +112 -0
- gebra-0.0.1.dist-info/WHEEL +4 -0
- gebra-0.0.1.dist-info/entry_points.txt +5 -0
- gebra-0.0.1.dist-info/licenses/LICENSE +201 -0
- 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
|
+
]
|