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
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
"""``GebraContractError`` — the decoration-time refusal of ANNOTATION-API-SPEC §1.
|
|
2
|
+
|
|
3
|
+
§1 puts the annotation surface's *errors* in exactly one place: "Decoration-time consistency
|
|
4
|
+
rules (violations raise ``GebraContractError`` at import time — cheap, early, never at
|
|
5
|
+
extraction)". Everything else on the annotation surface degrades instead: the sidecar's
|
|
6
|
+
validation is warning-grade "because the sidecar is config and extraction stays total" (§2),
|
|
7
|
+
the cross-surface precedence conflicts are warnings (§3, DEC-07), and even a resolved contract
|
|
8
|
+
that violates a §1 invariant across surfaces is repaired-with-a-warning rather than raised
|
|
9
|
+
(§3). So this exception says something narrow and specific: **one author's own decorator
|
|
10
|
+
stack contradicts itself**, and "a single author's stack has no drift to excuse".
|
|
11
|
+
|
|
12
|
+
Where it is raised is part of the meaning. A decorator runs when the defining module is
|
|
13
|
+
imported, so a violation surfaces at ``import my_agent``, before any graph is built and long
|
|
14
|
+
before ``gebra.extract()`` — which is the whole point of §1 putting these four rules here
|
|
15
|
+
rather than in the resolved-contract pass.
|
|
16
|
+
|
|
17
|
+
**Why one class with a reason code**, rather than a hierarchy: the same reasoning
|
|
18
|
+
:mod:`gebra.extraction.errors` records for :class:`~gebra.extraction.errors.ExtractionError`.
|
|
19
|
+
The refusals are one posture with several causes, and a caller that wants to branch does it
|
|
20
|
+
on :attr:`GebraContractError.reason` — a stable string — exactly as callers branch on
|
|
21
|
+
:class:`~gebra.ir.identity.NodeIdErrorReason`. It subclasses :class:`Exception` rather than
|
|
22
|
+
``TypeError`` or ``ValueError`` because the causes are split between the two: a duplicate
|
|
23
|
+
slot is neither a wrong type nor a bad value.
|
|
24
|
+
|
|
25
|
+
Nothing here imports langgraph, opens a socket, or executes anything (WA-07).
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
from enum import Enum
|
|
31
|
+
|
|
32
|
+
__all__ = ["ContractErrorReason", "GebraContractError"]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class ContractErrorReason(str, Enum):
|
|
36
|
+
"""Why decoration was refused — a stable code to branch on.
|
|
37
|
+
|
|
38
|
+
The first four are the four §1 consistency rules, one code each, so that "each rule
|
|
39
|
+
raises" is a checkable statement rather than a shared code with a variable message. The
|
|
40
|
+
last three are refusals of a *shape* the surface does not have: a slot that is not one
|
|
41
|
+
of the nine, a value that is not of the slot's kind, and a target that cannot carry the
|
|
42
|
+
attribute at all.
|
|
43
|
+
|
|
44
|
+
Attributes:
|
|
45
|
+
DUPLICATE_SLOT: A slot was set twice across one decorator stack. §1: "Each slot is
|
|
46
|
+
settable **at most once** across a decorator stack; a duplicate slot assignment
|
|
47
|
+
is an error, not a merge — **regardless of value, identical duplicates
|
|
48
|
+
included**." Deliberately stricter than §3's cross-surface rule, where identical
|
|
49
|
+
values are not a conflict.
|
|
50
|
+
PURE_EFFECT_EXCLUSIVE: ``pure=True`` and a non-empty ``effects`` were both declared
|
|
51
|
+
(decision D-011). Checked over the whole stack, so declaring them through two
|
|
52
|
+
different decorators is caught the same way as declaring both at once.
|
|
53
|
+
UNKNOWN_EFFECT_TAG: An ``effects`` tag outside the closed D-011 vocabulary
|
|
54
|
+
:data:`~gebra.annotations.slots.EFFECT_TAGS`. §1: "an unknown tag is an error".
|
|
55
|
+
DETERMINISTIC_SEED_REQUIRED: The ``deterministic`` object form was used without
|
|
56
|
+
``seed``. §1 names the case outright: "``@gebra.deterministic(temperature=0.0)``
|
|
57
|
+
without ``seed=`` raises at decoration time"; the frozen ledger §3 shape
|
|
58
|
+
``{seed: int, temperature?: number}`` owns the ruling.
|
|
59
|
+
UNKNOWN_SLOT: A keyword that is not one of the nine annotatable slots — a typo, or
|
|
60
|
+
one of the slots §1 puts out of annotation reach ("extracted or computed, never
|
|
61
|
+
annotated").
|
|
62
|
+
SLOT_VALUE_INVALID: A slot's value is not of that slot's kind — a bare string where
|
|
63
|
+
a sequence of state keys is meant, a non-string effect tag, an ``args_schema``
|
|
64
|
+
that is not a JSON object.
|
|
65
|
+
ATTACHMENT_IMPOSSIBLE: The target cannot carry ``__gebra_contract__`` at all — a
|
|
66
|
+
slotted or frozen object, a ``functools.partial``. §6 names this case and names
|
|
67
|
+
its answer: "the **sidecar is the designated fallback**".
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
DUPLICATE_SLOT = "duplicate-slot"
|
|
71
|
+
PURE_EFFECT_EXCLUSIVE = "pure-effect-exclusive"
|
|
72
|
+
UNKNOWN_EFFECT_TAG = "unknown-effect-tag"
|
|
73
|
+
DETERMINISTIC_SEED_REQUIRED = "deterministic-seed-required"
|
|
74
|
+
UNKNOWN_SLOT = "unknown-slot"
|
|
75
|
+
SLOT_VALUE_INVALID = "slot-value-invalid"
|
|
76
|
+
ATTACHMENT_IMPOSSIBLE = "attachment-impossible"
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class GebraContractError(Exception):
|
|
80
|
+
"""A decorator stack contradicts itself — raised at import time (§1).
|
|
81
|
+
|
|
82
|
+
Attributes:
|
|
83
|
+
reason: The :class:`ContractErrorReason` code — match on this, not on the message.
|
|
84
|
+
slot: The annotation slot the refusal is about, as its IR name, or ``None`` for a
|
|
85
|
+
refusal that is not about one slot (an unknown keyword, an unattachable target).
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
def __init__(
|
|
89
|
+
self, message: str, *, reason: ContractErrorReason, slot: str | None = None
|
|
90
|
+
) -> None:
|
|
91
|
+
super().__init__(message)
|
|
92
|
+
self.reason = reason
|
|
93
|
+
self.slot = slot
|