theoremql 0.3.1__py3-none-any.whl

theorem/__init__.py

@@ -0,0 +1,54 @@
+"""theorem: a graph query and construction language agents can't get wrong.
+
+The whole surface an embedding application needs:
+
+    from theorem import Schema, Session
+
+    with Session("mydb", Schema()) as db:
+        print(db.run('derive class supplier from entity with {country: str}'))
+        print(db.run('assert supplier {name: "VoltaChem", country: "DE"} as v'))
+        print(db.run('find supplier where country = "DE" as s\\nreturn s.name'))
+
+`Schema()` is the base schema: `entity` to derive domain classes from,
+plus the document classes the ingest pipeline uses. `Schema.supply_chain()`
+adds the demo classes the tutorial is written against.
+"""
+
+from .canonical import CanonicalError, canonical
+from .engine.executor import ExecError, Limits, limits
+from .engine.storage import Store, StoreError, StoreLocked
+from .ingest.bulk import LoadError, load_edges, load_nodes
+from .parser import ParseError, parse
+from .prompt import Answer, agent_prompt, answer, repair_prompt
+from .schema import ClassDef, EdgeDef, Schema
+from .session import Session
+from .verifier import VerifyError, verify
+
+__version__ = "0.3.1"
+
+__all__ = [
+    "Answer",
+    "CanonicalError",
+    "ClassDef",
+    "EdgeDef",
+    "ExecError",
+    "Limits",
+    "LoadError",
+    "ParseError",
+    "Schema",
+    "Session",
+    "Store",
+    "StoreError",
+    "StoreLocked",
+    "VerifyError",
+    "__version__",
+    "agent_prompt",
+    "answer",
+    "canonical",
+    "limits",
+    "load_edges",
+    "load_nodes",
+    "parse",
+    "repair_prompt",
+    "verify",
+]

theorem/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

theorem/ast_nodes.py

@@ -0,0 +1,175 @@
+"""AST node definitions for theorem statements.
+
+Col is a tuple of dotted path segments: ("sups", "name") for sups.name.
+Cond is a list of (joiner, Clause) pairs; the first joiner is always "and".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+Col = tuple[str, ...]
+
+
+@dataclass
+class Clause:
+    col: Col
+    op: str  # = != > >= < <= contains
+    value: object
+
+
+Cond = list[tuple[str, Clause]]  # joiner is "and" | "or"
+
+
+@dataclass
+class Stmt:
+    line: int = field(default=0, kw_only=True)
+
+
+@dataclass
+class Find(Stmt):
+    target: str  # class name, or "nodes" | "dup_candidates" | "class"
+    cond: Cond
+    name: str
+    order_by: Col | None = None
+    desc: bool = False
+
+
+@dataclass
+class Follow(Stmt):
+    src: str
+    edge: str
+    role: str
+    name: str
+    cond: Cond = field(default_factory=list)  # filters the arrival node
+    optional: bool = False  # "or none": keep rows that matched nothing
+    upto: int | None = None  # "upto N": walk 1..N times; None means once,
+    #                          0 means "upto any", to exhaustion
+
+
+@dataclass
+class Or(Stmt):
+    """Separates alternative branches; their results are unioned."""
+
+
+@dataclass
+class Keep(Stmt):
+    """Filter the rows that exist at this point, groups included."""
+
+    name: str
+    cond: Cond
+
+
+@dataclass
+class GroupBy(Stmt):
+    col: Col
+    name: str
+
+
+@dataclass
+class Aggregate(Stmt):
+    op: str  # count sum avg min max
+    distinct: bool
+    col: Col
+    name: str
+
+
+@dataclass
+class Compute(Stmt):
+    left: Col
+    op: str  # plus minus times over same
+    right: Col
+    name: str
+
+
+@dataclass
+class Return(Stmt):
+    cols: list[Col]
+    order_by: Col | None
+    desc: bool
+    limit: int | None
+    budget: int  # defaulted to 2000 when unstated
+    after: str | None  # position token @t-N
+    distinct: bool = False  # dedup on the projected values, not identity
+
+
+@dataclass
+class Continue(Stmt):
+    handle: str  # continuation token @cXXXX
+    budget: int
+
+
+@dataclass
+class AssertNode(Stmt):
+    cls: str
+    props: dict[str, object]
+    source: str | None
+    name: str
+
+
+@dataclass
+class AssertEdge(Stmt):
+    edge: str
+    role_refs: dict[str, str]  # role name -> binding name or node id
+    source: str | None
+
+
+@dataclass
+class Merge(Stmt):
+    a: str
+    b: str
+    policy: str  # "newest" or "source <provenance>"
+
+
+@dataclass
+class Distinct(Stmt):
+    a: str
+    b: str
+    reason: str
+
+
+@dataclass
+class Refine(Stmt):
+    ref: str
+    into_cls: str
+    mapping: dict[str, str]  # target prop -> source column name
+    name: str
+
+
+@dataclass
+class Compact(Stmt):
+    src: str
+    name: str
+    props: dict[str, object]
+
+
+@dataclass
+class Retire(Stmt):
+    ref: str
+    reason: str
+
+
+@dataclass
+class Flag(Stmt):
+    ref: str
+    reason: str
+
+
+@dataclass
+class DeriveClass(Stmt):
+    name: str
+    base: str
+    props: dict[str, str]  # prop name -> type name (str|int|float|bool)
+    quota: int | None = None
+    dedup: float | None = None
+
+
+@dataclass
+class DeriveEdge(Stmt):
+    name: str
+    roles: dict[str, str]  # role name -> class name, exactly two
+
+
+@dataclass
+class SchemaStmt(Stmt):
+    pass

theorem/canonical.py

@@ -0,0 +1,200 @@
+"""Render a parsed program back to its one canonical spelling.
+
+The language has exactly one way to write each operation, so two correct
+answers to the same question are the same program. That is what makes a
+plan cache and an audit log possible. It held of the text until the
+parser started accepting one redundant spelling, a condition qualified by
+the binding its own statement creates, and normalizing it away.
+
+Printing the parse restores the property at the level a cache can use:
+
+    canonical(query) == canonical(other)   iff   they are the same program
+
+Round-tripping is the test that keeps this honest. `parse(canonical(p))`
+must equal `parse(p)` for every program, which is checked against every
+query the benchmark has ever generated.
+"""
+
+from __future__ import annotations
+
+from .ast_nodes import (
+    Aggregate,
+    AssertEdge,
+    AssertNode,
+    Clause,
+    Col,
+    Compact,
+    Compute,
+    Cond,
+    Continue,
+    DeriveClass,
+    DeriveEdge,
+    Distinct,
+    Find,
+    Flag,
+    Follow,
+    GroupBy,
+    Keep,
+    Merge,
+    Or,
+    Refine,
+    Retire,
+    Return,
+    SchemaStmt,
+    Stmt,
+)
+
+
+class CanonicalError(Exception):
+    """A statement this printer does not know how to render."""
+
+
+def canonical(program: str) -> str:
+    """The canonical text of a program, given its text."""
+    from .parser import parse
+
+    return render(parse(program))
+
+
+def render(stmts: list[Stmt]) -> str:
+    return "\n".join(render_stmt(s) for s in stmts)
+
+
+def _col(col: Col) -> str:
+    return ".".join(col)
+
+
+def _quoted(v: str) -> str:
+    """A string literal, with the escapes the parser undoes put back.
+
+    Backslash first, so escaping a quote does not double the backslash
+    that escapes it.
+    """
+    return '"' + v.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _literal(v: object) -> str:
+    if type(v).__name__ == "_Missing":
+        return "none"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, str):
+        return _quoted(v)
+    if isinstance(v, float) and v.is_integer():
+        # 3.0 and 3 compare equal and mean the same filter; one spelling.
+        return str(int(v))
+    return str(v)
+
+
+def _clause(c: Clause) -> str:
+    return f"{_col(c.col)} {c.op} {_literal(c.value)}"
+
+
+def _cond(cond: Cond) -> str:
+    out = []
+    for i, (joiner, clause) in enumerate(cond):
+        out.append(_clause(clause) if i == 0 else f"{joiner} {_clause(clause)}")
+    return " ".join(out)
+
+
+def _where(cond: Cond) -> str:
+    return f" where {_cond(cond)}" if cond else ""
+
+
+def _order(col: Col | None, desc: bool) -> str:
+    if col is None:
+        return ""
+    return f" order by {_col(col)}" + (" desc" if desc else "")
+
+
+def _props(props: dict) -> str:
+    return "{" + ", ".join(f"{k}: {_literal(v)}" for k, v in props.items()) + "}"
+
+
+def render_stmt(stmt: Stmt) -> str:
+    match stmt:
+        case Find(target=t, cond=cond, name=n, order_by=ob, desc=d):
+            # The condition comes before `as`, which is the spelling the
+            # grammar leads with; the trailing form parses to the same tree.
+            return f"find {t}{_where(cond)}{_order(ob, d)} as {n}"
+        case Follow(
+            src=src, edge=e, role=r, name=n, cond=cond, optional=opt, upto=upto
+        ):
+            reach = ""
+            if upto == 0:
+                reach = " upto any"
+            elif upto is not None and upto != 1:
+                reach = f" upto {upto}"
+            tail = " or none" if opt else ""
+            return f"follow {src} {e} {r}{_where(cond)}{reach} as {n}{tail}"
+        case Or():
+            return "or"
+        case GroupBy(col=col, name=n):
+            return f"group by {_col(col)} as {n}"
+        case Aggregate(op=op, distinct=dist, col=col, name=n):
+            return f"{op}{' distinct' if dist else ''} {_col(col)} as {n}"
+        case Keep(name=n, cond=cond):
+            return f"keep {n} where {_cond(cond)}"
+        case Compute(left=lhs, op=op, right=rhs, name=n):
+            return f"compute {_col(lhs)} {op} {_col(rhs)} as {n}"
+        case Return(
+            cols=cols,
+            order_by=ob,
+            desc=d,
+            limit=lim,
+            budget=budget,
+            after=after,
+            distinct=dist,
+        ):
+            out = "return" + (" distinct" if dist else "")
+            out += " " + ", ".join(_col(c) for c in cols)
+            out += _order(ob, d)
+            if lim is not None:
+                out += f" limit {lim}"
+            if budget != 2000:  # the default is not written
+                out += f" budget {budget} tokens"
+            if after is not None:
+                out += f" after {after}"
+            return out
+        case Continue(handle=h, budget=budget):
+            out = f"continue {h}"
+            if budget != 2000:
+                out += f" budget {budget} tokens"
+            return out
+        case SchemaStmt():
+            return "schema"
+        case AssertNode(cls=cls, props=props, source=src, name=n):
+            out = f"assert {cls} {_props(props)}"
+            if src:
+                out += f" source {src}"
+            return out + f" as {n}"
+        case AssertEdge(edge=e, role_refs=roles, source=src):
+            args = ", ".join(f"{r}: {v}" for r, v in roles.items())
+            out = f"assert edge {e}({args})"
+            return out + (f" source {src}" if src else "")
+        case Merge(a=a, b=b, policy=policy):
+            out = f"merge {a}, {b}"
+            return out + (f" prefer {policy}" if policy else "")
+        case Distinct(a=a, b=b, reason=reason):
+            return f"distinct {a}, {b} reason {_quoted(reason)}"
+        case Refine(ref=ref, into_cls=cls, mapping=mapping, name=n):
+            cols = ", ".join(f"{k}: col {_quoted(v)}" for k, v in mapping.items())
+            return f"refine {ref} into {cls} with {{{cols}}} as {n}"
+        case Compact(src=src, name=n, props=props):
+            return f"compact {src} as {n} {_props(props)}"
+        case Retire(ref=ref, reason=reason):
+            return f"retire {ref} reason {_quoted(reason)}"
+        case Flag(ref=ref, reason=reason):
+            return f"flag {ref} reason {_quoted(reason)}"
+        case DeriveClass(name=n, base=base, props=props, quota=quota, dedup=dedup):
+            decls = ", ".join(f"{k}: {v}" for k, v in props.items())
+            out = f"derive class {n} from {base} with {{{decls}}}"
+            if quota is not None:
+                out += f" quota {quota}"
+            if dedup is not None:
+                out += f" dedup {dedup}"
+            return out
+        case DeriveEdge(name=n, roles=roles):
+            args = ", ".join(f"{r}: {c}" for r, c in roles.items())
+            return f"derive edge {n}({args})"
+    raise CanonicalError(f"cannot render {type(stmt).__name__}")