relationalai 0.13.0__py3-none-any.whl → 0.13.0.dev0__py3-none-any.whl

relationalai/tools/typer_debugger.py

@@ -0,0 +1,93 @@
+import os
+import re
+from nicegui import ui
+import json
+import dataclasses
+
+
+#--------------------------------------------------
+# Data
+#--------------------------------------------------
+last_mod_time = None
+current_content: dict[str, str] = dict()
+
+def parse_file(jsonl_content):
+    content = dict()
+    lines = jsonl_content.strip().split('\n')
+    for line in lines:
+        data = json.loads(line)
+        content[data['id']] = data['content']
+    return content
+
+def poll():
+    global last_mod_time
+    global current_content
+    # Check the last modification time of the file
+    try:
+        mod_time = os.path.getmtime('typer_debug.jsonl')
+        if last_mod_time is None or mod_time > last_mod_time:
+            last_mod_time = mod_time
+            # File has changed, read and parse the new content
+            with open('typer_debug.jsonl', 'r') as file:
+                content = file.read()
+                if content:
+                    current_content = parse_file(content)
+                    view.refresh()
+    except FileNotFoundError:
+        pass
+
+#--------------------------------------------------
+# UI
+#--------------------------------------------------
+
+@ui.refreshable
+def view():
+    with ui.column():
+        # model
+        with ui.row():
+            with ui.column():
+                ui.label("Model").style("font-weight: bold;")
+                code(current_content.get('model', ''), language='metamodel')
+            with ui.column():
+                ui.label("Typed Model").style("font-weight: bold;")
+                code(current_content.get('typed_model', ''), language='metamodel')
+        # typer
+        with ui.row():
+            ui.label("Type Propagation Network").style("font-weight: bold;")
+            ui.mermaid(current_content.get('model_net', ''),
+                       {"maxEdges":10000}
+            ).style("display:flex; padding:0px 0px 0px 15px; gap:30px; overflow: auto;").on('error', lambda e: print(e.args['message']))
+        # query
+        with ui.row():
+            with ui.column():
+                ui.label("Query").style("font-weight: bold;")
+                code(current_content.get('query', ''), language='rel')
+            with ui.column():
+                ui.label("Typed Query").style("font-weight: bold;")
+                code(current_content.get('typed_query', ''), language='rel')
+
+        # typer
+        with ui.row():
+            ui.label("Type Propagation Network").style("font-weight: bold;")
+            ui.mermaid(current_content.get('query_net', ''), {"maxEdges":10000}).style("display:flex; padding:0px 0px 0px 15px; gap:30px; overflow: auto;")
+
+def code(c, language="python"):
+    if language == "rel":
+        language = "ruby"
+    if language == "lqp":
+        language = "clojure"
+    c = re.sub(r"→", "->", c)
+    c = re.sub(r"⇑", "^", c)
+    return ui.code(c, language=language).style("border:none; margin:0; padding-right: 30px; ").classes("w-full")
+
+def main(host="0.0.0.0", port=8082):
+    global checkboxes
+    global toggles
+    ui.dark_mode(True)
+    view()
+
+    ui.timer(1, poll)
+    ui.run(reload=False, host=host, port=port)
+
+if __name__ in {"__main__", "__mp_main__"}:
+    main()

relationalai/util/dataclasses.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field, fields, is_dataclass
+from functools import lru_cache
+from typing import Tuple, Any
+
+def is_dataclass_instance(obj) -> bool:
+    """Checks if the object is a dataclass instance, excluding the class itself."""
+    return is_dataclass(obj) and not isinstance(obj, type)
+
+def print_tree(node, field_name=None, indent=0, hide_fields=[], seen=set()):
+    """Recursively print a dataclass tree structure.
+
+    Args:
+        node: The dataclass instance or value to print.
+        field_name: Optional name of the field (for nested calls).
+        indent: Current indentation level.
+        hide_fields: List of field names to hide in the output."""
+    if id(node) in seen:
+        _indent_print(indent, "<recursion>", field_name)
+        return
+    seen.add(id(node))
+    if is_dataclass_instance(node):
+        _indent_print(indent, f"{node.__class__.__name__}:", field_name)
+        next = indent + 2
+        for field in fields(node):
+            if field.name not in hide_fields:
+                print_tree(getattr(node, field.name), field.name, next, hide_fields)
+    elif isinstance(node, list) or isinstance(node, tuple):
+        # just ignore sequences that are empty
+        if node:
+            _indent_print(indent, f"[", field_name)
+            next = indent + 2
+            for item in node:
+                print_tree(item, None, next, hide_fields)
+            _indent_print(indent, f"]")
+    else:
+        _indent_print(indent, str(node), field_name)
+
+
+def _indent_print(indent, value, field_name=None):
+    if field_name:
+        print(" " * indent + f"{field_name}: {value}")
+    else:
+        print(" " * indent + value)

relationalai/util/docutils.py

@@ -0,0 +1,40 @@
+from typing import Any, TypeVar
+from typing import Optional
+
+T = TypeVar('T')
+def include_in_docs(obj: T) -> T:
+    """Marks an object for inclusion in documentation.
+
+    Parameters
+    ----------
+    obj : Any
+        The object to mark for inclusion in documentation.
+
+    Examples
+    --------
+    Use as a decorator to mark a function for inclusion in documentation:
+
+    >>> @include_in_docs
+    >>> def double(x: int):
+    >>>     return x * 2
+
+    Use as a decorator to mark classes and methods for inclusion in documentation:
+
+    >>> @include_in_docs
+    >>> class Dog:
+    >>>     def __init__(self, name: str):
+    >>>         self.name = name
+    >>>     @include_in_docs
+    >>>     def bark(self):
+    >>>         return "Woof!"
+
+    To mark a module for inclusion in the documentation, set the
+    `__include_in_docs__` attribute to True in the module itself.
+    You do not need to use this function for modules.
+
+    For attributes, module and class-level attributes, simply provide
+    a docstring and they will be included in the documentation. There is
+    no need to use this function for attributes.
+    """
+    setattr(obj, "__include_in_docs__", True)
+    return obj

relationalai/util/error.py

@@ -0,0 +1,199 @@
+from dataclasses import dataclass, field
+from io import StringIO
+from typing import Any, NoReturn, Optional
+import html
+
+from .source import SourcePos
+from .tracing import get_tracer
+
+from rich import box
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.syntax import Syntax
+from rich.table import Table as RichTable
+from rich.text import Text
+
+#------------------------------------------------------
+# Parts
+#------------------------------------------------------
+
+@dataclass
+class Source:
+    pos: SourcePos
+    orig_line: int
+
+    def __init__(self, pos: SourcePos):
+        self.orig_line = pos.line or 0
+        self.pos = pos.block
+
+
+@dataclass
+class Table:
+    headers: list[str]
+    rows: list[list[str]]
+
+Part = str|Source|Table
+
+#------------------------------------------------------
+# Diagnostic
+#------------------------------------------------------
+
+class Diagnostic():
+    def __init__(self, name: str, message:str, parts: list[Part] = [], severity: str = "error"):
+        self.name = name
+        self.message = message
+        self.parts = parts
+        self.severity = severity  # "error", "warning", "info"
+
+    def to_dict(self) -> dict:
+        parts_json: list[dict] = []
+        for p in self.parts:
+            if isinstance(p, str):
+                parts_json.append({"kind": "text", "text": p})
+            elif isinstance(p, Source):
+                parts_json.append({"kind": "source", "file": p.pos.file, "line": p.pos.line, "source": p.pos.source, "orig_line": p.orig_line})
+            elif isinstance(p, Table):
+                parts_json.append({"kind": "table", "headers": p.headers, "rows": p.rows})
+        return {"name": self.name, "message": self.message, "severity": self.severity, "parts": parts_json}
+
+#------------------------------------------------------
+# Emitters
+#------------------------------------------------------
+
+class RichEmitter:
+    """
+    Returns a pretty terminal string (no side effects).
+    """
+    def emit(self, diag: Diagnostic) -> str:
+        buf = StringIO()
+        # write to our buffer, not the real terminal
+        console = Console(file=buf, record=False, color_system="auto", soft_wrap=False, force_terminal=True)
+        sev_style = {"error": "bold red", "warning": "bold yellow", "info": "bold cyan"}.get(diag.severity, "bold")
+        sev_sub_style = {"error": "red", "warning": "yellow", "info": "cyan"}.get(diag.severity, "cyan")
+
+        # Title
+        title_text = Text(f"[{diag.name}] ", style=sev_style)
+        title_text.append(diag.message, style="bold")
+
+        # Collect all parts into a group
+        parts_renderables:list[Any] = [title_text]
+        loc = None
+            # parts_renderables.append(Rule(style=sev_style))
+
+        for i, part in enumerate(diag.parts):
+            parts_renderables.append(Text(""))  # spacer
+            if isinstance(part, str):
+                parts_renderables.append(Text.from_markup(part))
+            elif isinstance(part, Source) and part.pos.source:
+                # header = Text(f"› {part.pos.file}:{part.orig_line}")
+                if not loc:
+                    loc = Text(f">> {part.pos.file}:{part.orig_line}", style="dim")
+                lexer = "python" if str(part.pos.file).endswith(".py") else "text"
+                num_lines = part.pos.source.count("\n") + 1
+                highlight_lines = set([part.orig_line]) if num_lines > 1 else set()
+                start_line = part.pos.line or 0
+                parts_renderables.append(
+                    Syntax(part.pos.source.rstrip("\n"), lexer, line_numbers=True, background_color="default", word_wrap=True, start_line=start_line, highlight_lines=highlight_lines)
+                )
+            elif isinstance(part, Table):
+                t = RichTable(show_header=True, expand=False, show_lines=False, padding=(0,1), box=box.SIMPLE_HEAD, border_style=None)
+                for h in part.headers:
+                    t.add_column(h)
+                for row in part.rows:
+                    t.add_row(*[str(c) for c in row])
+                parts_renderables.append(t)
+
+        # One big group, inside one Panel
+        if loc:
+            parts_renderables.insert(1, loc)
+        group = Group(*parts_renderables)
+        console.print(Panel(group, border_style=sev_style))
+
+        return buf.getvalue()
+
+class HTMLEmitter:
+    """
+    Returns inline-CSS HTML string (no side effects).
+    """
+    def emit(self, diag: Diagnostic) -> str:
+        css = """
+<style>
+.diag { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, Apple Color Emoji, Segoe UI Emoji; }
+.hdr { font-weight: 700; margin: 8px 0; }
+.hdr.err { color: #c62828 } .hdr.warn { color: #b26a00 } .hdr.info { color: #006064 }
+.block { margin: 8px 0 14px 0; }
+.code { background:#0b0d10; color:#e6edf3; padding:10px 12px; border-radius:8px; overflow:auto; white-space:pre; }
+.file { color:#9aa4b2; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; margin:4px 0; }
+.table { border-collapse: collapse; margin: 8px 0; }
+.table th, .table td { border: 1px solid #e0e0e0; padding: 6px 8px; font-size: 0.95rem; }
+.table th { background: #f7f7f7; text-align: left; }
+</style>
+"""
+        sev_cls = {"error": "err", "warning": "warn", "info": "info"}.get(diag.severity, "info")
+        hdr = f'<div class="hdr {sev_cls}">[{html.escape(diag.name)}] {html.escape(diag.message)}</div>'
+
+        parts_html: list[str] = []
+        for part in diag.parts:
+            if isinstance(part, str):
+                parts_html.append(f'<div class="block">{html.escape(part)}</div>')
+            elif isinstance(part, Source) and part.pos.source:
+                file_line = f'{html.escape(str(part.pos.file))}:{part.pos.line}'
+                code = html.escape(part.pos.source.rstrip("\n"))
+                parts_html.append(f'<div class="block"><div class="file">-- {file_line}</div><pre class="code"><code>{code}</code></pre></div>')
+            elif isinstance(part, Table):
+                head = "".join(f"<th>{html.escape(h)}</th>" for h in part.headers)
+                body = "".join("<tr>" + "".join(f"<td>{html.escape(str(c))}</td>" for c in row) + "</tr>" for row in part.rows)
+                parts_html.append(f'<div class="block"><table class="table"><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>')
+
+        return f'<div class="diag">{css}{hdr}{"".join(parts_html)}</div>'
+
+#------------------------------------------------------
+# Custom Exception classes
+#------------------------------------------------------
+
+class RAIWarning(UserWarning):
+    """Warnings emitted by RAI."""
+
+class RAIException(Exception):
+    """Exception raised to signal a diagnostic error."""
+    def __init__(self, diag: Diagnostic):
+        self.diagnostic = diag
+        super().__init__(f"[{diag.name}] {diag.message}")
+
+#------------------------------------------------------
+# Funcs
+#------------------------------------------------------
+
+def warn(name: str, message: str, parts: Optional[list[Part]] = None) -> Diagnostic:
+    from .runtime import ENV  # avoid circular import
+    diag = Diagnostic(name, message, parts or [], severity="warning")
+    ENV.warn(diag)
+    return diag
+
+def err(name: str, message: str, parts: Optional[list[Part]] = None) -> Diagnostic:
+    from .runtime import ENV  # avoid circular import
+    diag = Diagnostic(name, message, parts or [], severity="error")
+    # Do not raise here; caller may choose to continue. Just route it.
+    ENV.err(diag)  # default raises; override ENV to change behavior
+    return diag  # (unreached in default env)
+
+def exc(name: str, message: str, parts: Optional[list[Part]] = None) -> NoReturn:
+    from .runtime import ENV  # avoid circular import
+    """Always raise after routing (handy for short-circuiting)."""
+    diag = Diagnostic(name, message, parts or [], severity="error")
+    ENV.err(diag, exception=True)  # raises DiagnosticException by default
+    raise RuntimeError("Unreachable")  # for type checkers
+
+def source(obj:Any) -> Source:
+    if isinstance(obj, SourcePos):
+        return Source(pos=obj)
+
+    source = getattr(obj, "_source", None) or getattr(obj, "source", None)
+    if source is None:
+        raise ValueError("Object has no source information")
+
+    return Source(source)
+
+def table(headers: list[str] = [], rows: list[list[str]] = []) -> Table:
+    return Table(headers=headers, rows=rows)

relationalai/util/format.py

@@ -1,123 +1,65 @@
-def humanized_duration(ms: int) -> str:
-    """Format duration in milliseconds to human-readable format with spaces.
+"""Formatting utilities for RelationalAI."""
 
-    Converts milliseconds to a human-readable string with up to 3 time components
-    (days, hours, minutes, seconds) separated by spaces.
+from __future__ import annotations
+
+
+def format_duration(seconds: float) -> str:
+    """Format a duration in seconds as a human-readable string.
 
     Args:
-        ms: Duration in milliseconds
+        seconds: Duration in seconds (can be fractional)
 
     Returns:
-        Formatted string like '1h 2m 3.5s' (max 3 components).
-        Returns empty string for zero duration.
+        Formatted duration string (e.g., "1.2s", "3m 45s", "1h 23m 45s")
 
     Examples:
-        >>> humanized_duration(1000)
-        '1.0s'
-        >>> humanized_duration(90000)
-        '1m 30.0s'
-        >>> humanized_duration(3665000)
-        '1h 1m 5.0s'
-        >>> humanized_duration(95400000)
-        '1d 2h 30m'
+        >>> format_duration(0.5)
+        '0.5s'
+        >>> format_duration(65.5)
+        '1m 5s'
+        >>> format_duration(3661)
+        '1h 1m 1s'
     """
-    # Convert milliseconds to other time units
-    seconds = ms / 1000
-    minutes = seconds / 60
-    hours = minutes / 60
-    days = hours / 24
+    if seconds < 0:
+        return "0s"
+
+    if seconds < 60:
+        # Less than a minute: show seconds with appropriate precision
+        if seconds < 1:
+            # Sub-second: show 2 decimal places
+            return f"{seconds:.2f}s".rstrip("0").rstrip(".")
+        elif seconds < 10:
+            # 1-10 seconds: show 1 decimal place
+            return f"{seconds:.1f}s".rstrip("0").rstrip(".")
+        else:
+            # 10+ seconds: show as integer
+            return f"{int(seconds)}s"
 
-    # Extract display components using modulo to get remainders
-    display_days = int(days)
-    display_hours = int(hours % 24)
-    display_minutes = int(minutes % 60)
-    display_seconds = seconds % 60
+    # Calculate hours, minutes, and remaining seconds
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = seconds % 60
 
-    # Build list of non-zero time components
     parts = []
-    if display_days > 0:
-        parts.append(f"{display_days}d")
-    if display_hours > 0:
-        parts.append(f"{display_hours}h")
-    if display_minutes > 0:
-        parts.append(f"{display_minutes}m")
-    if display_seconds > 0:
-        # Show seconds with one decimal place (no thousand separators for time)
-        parts.append(f"{display_seconds:.1f}s")
-
-    # Return up to 3 components, space-separated
-    return " ".join(parts[:3])
-
-
-def format_duration(duration_seconds: float) -> str:
-    """Format duration in seconds to human-readable format.
-
-    Args:
-        duration_seconds: Duration in seconds
-
-    Returns:
-        Formatted string like '500ms', '2.5s', '1m30s', '1h5m'
 
-    Examples:
-        >>> format_duration(0.5)
-        '500ms'
-        >>> format_duration(2.5)
-        '2.5s'
-        >>> format_duration(90)
-        '1m30s'
-        >>> format_duration(3665)
-        '1h1m'
-    """
-    # For durations less than 1 second, show milliseconds
-    if duration_seconds < 1:
-        milliseconds = round(duration_seconds * 1000)
-        # Handle edge case where rounding gives us 1000ms
-        if milliseconds >= 1000:
-            return "1.0s"
-        return f"{milliseconds}ms"
+    if hours > 0:
+        parts.append(f"{hours}h")
 
-    # For durations less than 1 minute, show seconds with one decimal
-    elif duration_seconds < 60:
-        return f"{round(duration_seconds, 1)}s"
+    if minutes > 0:
+        parts.append(f"{minutes}m")
 
-    # For durations less than 1 hour, show minutes and seconds
-    elif duration_seconds < 3600:
-        minutes = int(duration_seconds // 60)
-        seconds = int(duration_seconds % 60)
-        if seconds == 0:
-            return f"{minutes}m"
+    # Only show seconds if less than a minute has elapsed, or if it's a significant portion
+    if hours == 0 and minutes == 0:
+        # Show seconds with decimal if less than a minute
+        if secs < 1:
+            parts.append(f"{secs:.2f}s".rstrip("0").rstrip("."))
+        elif secs < 10:
+            parts.append(f"{secs:.1f}s".rstrip("0").rstrip("."))
         else:
-            return f"{minutes}m{seconds}s"
-    else:
-        hours = int(duration_seconds // 3600)
-        minutes = int((duration_seconds % 3600) // 60)
-        if minutes == 0:
-            return f"{hours}h"
-        else:
-            return f"{hours}h{minutes}m"
-
-def humanized_bytes(bytes: int) -> str:
-    """Format bytes to human-readable format."""
-    if bytes < 1024:
-        return f"{bytes} B"
-    elif bytes < 1024 ** 2:
-        return f"{bytes / 1024:.1f} KB"
-    elif bytes < 1024 ** 3:
-        return f"{bytes / 1024 ** 2:.1f} MB"
-    elif bytes < 1024 ** 4:
-        return f"{bytes / 1024 ** 3:.1f} GB"
-    else:
-        return f"{bytes / 1024 ** 4:.1f} TB"
+            parts.append(f"{int(secs)}s")
+    elif secs >= 1:
+        # Show seconds as integer if >= 1 second when we have minutes/hours
+        parts.append(f"{int(secs)}s")
 
-def str_to_bool(s):
-    # Adapted from snowflake's convert_str_to_bool
-    if s is None:
-        return None
-    if s.lower() in ("true", "t", "yes", "y", "on", "1"):
-        return True
-    if s.lower() in ("false", "f", "no", "n", "off", "0"):
-        return False
-    raise ValueError(f"Invalid boolean value: {s}")
+    return " ".join(parts) if parts else "0s"
 
-def default_serialize(obj):
-    return '<skipped>'