llmalchemy 1.4.1__py3-none-any.whl

llmalchemy/__init__.py

@@ -0,0 +1,6 @@
+"""Publicly exposed symbols."""
+
+from .agent import run
+from .tools import tool
+
+__all__ = ["run", "tool"]

llmalchemy/agent.py

@@ -0,0 +1,249 @@
+"""Contains the agentic loop and related utils."""
+
+import weakref
+from collections.abc import Generator, Iterator
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, cast
+
+from lmdk import Message, UserMessage, complete
+from pydantic import BaseModel, Field, create_model
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session
+
+from .code import execute, validate
+from .context import render
+from .tools import Tool, make_disclose_fn
+
+MAX_LOOPS = 20
+
+
+@dataclass
+class State:
+    """Contains the different objects whose state is modified through the agentic loop.
+
+    Attributes:
+        session: the sqlalchemy database connection
+        messages: the conversation history
+        namespace: symbols of the code environment that the agent uses
+    """
+
+    session: Session | None = None
+    messages: list[Message] = field(default_factory=list)
+    namespace: dict = field(default_factory=dict)
+
+
+class Output(BaseModel):
+    """Pydantic model to force the LM structured output."""
+
+    message: str = Field(description="The response shown to the user.")
+    code: str = Field(default="", description="The optional code to run.")
+
+
+class Signal(StrEnum):
+    """Signals emitted by the agentic loop to indicate current stage."""
+
+    COMPLETION = "COMPLETION"
+    VALIDATION = "VALIDATION"
+    EXECUTION = "EXECUTION"
+    EXCEEDED = "EXCEEDED"
+
+
+@dataclass(frozen=True)
+class Event:
+    """Base class for all events yielded by the agentic loop."""
+
+
+@dataclass(frozen=True)
+class SignalEvent(Event):
+    """A control-flow signal indicating the current stage."""
+
+    signal: Signal
+
+
+@dataclass(frozen=True)
+class MessageEvent(Event):
+    """A message appended to the conversation history."""
+
+    message: Message
+
+
+@dataclass(frozen=True)
+class SystemInstructionEvent(Event):
+    """The system instruction sent to the model."""
+
+    content: str
+
+
+def _complete(
+    state: State,
+    model: str,
+    system_instruction: str,
+    output_schema: type[Output],
+) -> Generator[Event, None, Output]:
+    """Single LM call: append the response, yield signals and the message, return parsed output."""
+    yield SignalEvent(Signal.COMPLETION)
+    response = complete(
+        model=model,
+        prompt=state.messages,
+        system_instruction=system_instruction,
+        output_schema=output_schema,
+    )
+    state.messages.append(response.message)
+    yield MessageEvent(response.message)
+    assert isinstance(response.output, Output)
+    return response.output
+
+
+def _build_output_schema(output_extensions: type[BaseModel] | None) -> type[Output]:
+    """Build the structured-output schema used by the agent loop.
+
+    When ``output_extensions`` is ``None``, the plain :class:`Output` model is
+    returned. Otherwise, a dynamic subclass is created whose fields are the
+    extension fields followed by ``message`` and ``code`` (in that order).
+
+    Ordering matters: fields emitted earlier in the structured output act as a
+    scratchpad for later fields (this is how chain-of-thought-in-schema works).
+    Typical uses are reasoning slots (e.g. ``thoughts: str`` or ARQ-style
+    ``user_intent`` / ``info_needed`` / ``info_missing``) and product fields
+    (``confidence``, ``citations``, ``suggested_followups``, …). The agent loop
+    only reads ``.message`` and ``.code``; extra fields ride along on the
+    yielded message object for the caller to consume.
+    """
+    if output_extensions is None:
+        return Output
+
+    extension_fields = {
+        name: (f.annotation, f) for name, f in output_extensions.model_fields.items()
+    }
+    base_fields = {name: (f.annotation, f) for name, f in Output.model_fields.items()}
+    # ``create_model``'s overloads don't accept ``**kwargs`` unpacking, so we
+    # cast to ``Any`` to silence the type checker without a per-call pragma.
+    return cast(Any, create_model)("Output", **extension_fields, **base_fields)
+
+
+def _init_session(state: State, base: type[DeclarativeBase]) -> None:
+    """Initialize the SQLAlchemy session when missing (first call)."""
+    if state.session is None:
+        engine = create_engine("sqlite://")
+        base.metadata.create_all(engine)
+        state.session = Session(engine)
+        # Dispose the engine (and close its pooled sqlite3.Connection) when
+        # the session is garbage-collected, to avoid ResourceWarnings.
+        weakref.finalize(state.session, engine.dispose)
+
+
+def _init_namespace(
+    state: State,
+    base: type[DeclarativeBase],
+    tools: list[Tool],
+) -> dict[str, str]:
+    """Populate or refresh the agent code execution namespace.
+
+    On the first call the namespace is empty, so all symbols are injected:
+    ``session``, ORM model classes, tool functions, and ``disclose``.
+    On follow-up calls only ``session`` is refreshed because the database
+    may have changed between calls (user side).
+
+    Returns:
+        A ``{name: description}`` dict of every injected **infrastructure**
+        symbol.  Tool symbols are excluded — their source of truth is the
+        ``Tool`` object itself, rendered separately by ``_render_tools_summary``.
+    """
+    descriptions: dict[str, str] = {}
+
+    state.namespace["session"] = state.session
+    descriptions["session"] = "a `sqlalchemy.orm.Session` connected to the database."
+
+    orm_classes = base.__subclasses__()
+    for cls in orm_classes:
+        state.namespace[cls.__name__] = cls
+    if orm_classes:
+        names = ", ".join(cls.__name__ for cls in orm_classes)
+        descriptions[names] = "ORM model classes (see schema above)."
+
+    for t in tools:
+        state.namespace[t.name] = t.fn
+
+    if tools:
+        state.namespace["disclose"] = make_disclose_fn(tools)
+        descriptions["disclose"] = (
+            "`disclose(name: str) -> str` — prints the full signature"
+            " and docstring of a tool. Call it before using a tool you haven't seen yet."
+        )
+
+    return descriptions
+
+
+def run(
+    state: State,
+    base: type[DeclarativeBase],
+    model: str,
+    tools: list[Tool] | None = None,
+    allowed_imports: list[str] | None = None,
+    prompt_template: str | Path | None = None,
+    output_extensions: type[BaseModel] | None = None,
+    thinking: bool = False,
+) -> Iterator[Event]:
+    """Execute the agentic loop.
+
+    An intermediate turn is one where the assistant message requests to run ``.code``.
+    The loop ends as soon as the assistant responds without code. Turn is returned to user.
+
+    Args:
+        state: Conversation, database state and python namespace (mutated in place).
+        base: SQLAlchemy declarative base that defines the db schema.
+        model: Model identifier forwarded to ``complete()``.
+        tools: User-provided tools the agent can call in generated code.
+        allowed_imports: Any vanilla module or third-party package that the agent can use.
+        output_extensions: Optional Pydantic model to force in the LM structured output.
+        thinking: Level of thinking for provider-native reasoning tokens. Not implemented yet.
+        prompt_template: Custom jinja system prompt. Should contain placeholders for:
+            - ``SCHEMA``: used to show agent the source code of ORM classes
+            - ``SYMBOLS``: used to show ageent all pre-loaded namespace symbols.
+            - ``TOOLS``: usedf to show the agent tool names + short descriptions.
+
+    Yields:
+        ``Event``: system instruction, loop signals, and conversation messages.
+    """
+    if thinking:
+        raise NotImplementedError("Native provider thinking is not yet wired through lmdk.")
+
+    # Initialize everything
+    tools = tools or []
+    allowed_imports = allowed_imports or []
+    output_schema = _build_output_schema(output_extensions)
+    _init_session(state, base)
+    descriptions = _init_namespace(state, base, tools)
+    system_instruction = render(base, tools, descriptions, prompt_template)
+    yield SystemInstructionEvent(system_instruction)
+
+    # First call to the model
+    output = yield from _complete(state, model, system_instruction, output_schema)
+    code = output.code
+
+    # Loop until model is over with the task
+    loops = 0
+    while code:
+        if loops >= MAX_LOOPS:
+            yield SignalEvent(Signal.EXCEEDED)
+            break
+        loops += 1
+
+        yield SignalEvent(Signal.VALIDATION)
+        if reason := validate(source=code, allowed_imports=allowed_imports):
+            message = UserMessage(f"Code rejected: {reason}")
+            state.messages.append(message)
+            yield MessageEvent(message)
+            output = yield from _complete(state, model, system_instruction, output_schema)
+            code = output.code
+            continue
+
+        yield SignalEvent(Signal.EXECUTION)
+        result = execute(source=code, namespace=state.namespace)
+        message = UserMessage(f"Execution result:\n{result}")
+        state.messages.append(message)
+        yield MessageEvent(message)
+        output = yield from _complete(state, model, system_instruction, output_schema)
+        code = output.code

llmalchemy/code.py

@@ -0,0 +1,149 @@
+"""Contains the logic for the sandboxed python env on which to run the agent requested code.
+
+HuggingFace has a very nice reference for further ideas:
+https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py
+"""
+
+import ast
+import contextlib
+import io
+import traceback
+
+FORBIDDEN_BUILTINS = frozenset(
+    {
+        "exec",
+        "eval",
+        "compile",
+        "__import__",
+        "open",
+        "exit",
+        "quit",
+        "breakpoint",
+        "input",
+        "getattr",
+        "setattr",
+        "delattr",
+        "globals",
+        "locals",
+        "vars",
+        "dir",
+    }
+)
+
+FORBIDDEN_MODULE_NAMES = frozenset(
+    {
+        "os",
+        "subprocess",
+        "sys",
+        "shutil",
+        "pathlib",
+        "importlib",
+    }
+)
+
+FORBIDDEN_ATTRIBUTES = frozenset(
+    {
+        "__globals__",
+        "__builtins__",
+        "__subclasses__",
+        "__bases__",
+        "__code__",
+        "__import__",
+        "__dict__",
+    }
+)
+
+
+def _check_import(node: ast.Import, allowed_imports: list[str]) -> str:
+    """Block imports whose root module is not in the whitelist."""
+    for alias in node.names:
+        root = alias.name.split(".")[0]
+        if root not in allowed_imports:
+            return f"Forbidden import: {alias.name}"
+    return ""
+
+
+def _check_import_from(node: ast.ImportFrom, allowed_imports: list[str]) -> str:
+    """Block star imports unconditionally; block modules not in the whitelist."""
+    for alias in node.names:
+        if alias.name == "*":
+            return f"Forbidden star import: from {node.module} import *"
+    if node.module:
+        root = node.module.split(".")[0]
+        if root not in allowed_imports:
+            return f"Forbidden import: {node.module}"
+    return ""
+
+
+def _check_name(node: ast.Name) -> str:
+    """Block dangerous builtin calls/references and dangerous module names."""
+    if node.id in FORBIDDEN_BUILTINS:
+        return f"Forbidden builtin: {node.id}"
+    if node.id in FORBIDDEN_MODULE_NAMES:
+        return f"Forbidden name: {node.id}"
+    return ""
+
+
+def _check_attribute(node: ast.Attribute) -> str:
+    """Block dangerous dunder attribute access."""
+    if node.attr in FORBIDDEN_ATTRIBUTES:
+        return f"Forbidden attribute access: {node.attr}"
+    return ""
+
+
+def validate(source: str, allowed_imports: list[str]) -> str:
+    """Use AST parsing against a set of rules to decide if the code is safe.
+
+    Args:
+        source: Python source code produced by the model.
+        allowed_imports: Whitelist of importable module names.
+
+    Returns:
+        ``""`` on success, or a human-readable reason string on rejection.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return f"Syntax error: {e.msg}"
+
+    reason = ""
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            reason = _check_import(node, allowed_imports)
+        elif isinstance(node, ast.ImportFrom):
+            reason = _check_import_from(node, allowed_imports)
+        elif isinstance(node, ast.Name):
+            reason = _check_name(node)
+        elif isinstance(node, ast.Attribute):
+            reason = _check_attribute(node)
+        # Exit if any checker populated `reason` -> code is invalid
+        if reason:
+            break
+
+    return reason
+
+
+def execute(source: str, namespace: dict) -> str:
+    """Execute *source* code requested by the Agent inside *namespace*.
+
+    Runs synchronously in the calling thread.  There is no timeout guard:
+    the model could theoretically generate an infinite loop that we cannot
+    catch at the AST validation level.
+
+    Args:
+        source: Python/SQLAlchemy source code produced by the model.
+        namespace: Dict of python symbols available during execution.
+            **Mutated in-place** — new bindings created by the code
+            persist in *namespace* after this call returns.
+
+    Returns:
+        A string with stdout output, a traceback, or a status message.
+    """
+    buf = io.StringIO()
+    try:
+        compiled = compile(source, "<agent>", "exec")
+        with contextlib.redirect_stdout(buf):
+            exec(compiled, namespace)
+        return buf.getvalue() or "Code executed successfully but produced no stdout."
+    except Exception:
+        return traceback.format_exc()

llmalchemy/context.py

@@ -0,0 +1,90 @@
+"""Contains the utils to engineer the context passed to the agent."""
+
+import inspect
+import re
+import warnings
+from pathlib import Path
+
+from lmdk import render_template
+from sqlalchemy.orm import DeclarativeBase
+
+from .tools import Tool
+
+_TEMPLATE_PATH = Path(__file__).parent / "prompt.jinja"
+
+_REQUIRED_MARKERS = ("SCHEMA", "SYMBOLS", "TOOLS")
+
+
+class LLMAlchemyPromptWarning(UserWarning):
+    """Warning for prompt templates missing one of the documented Jinja variables."""
+
+
+def _render_schema_source(base: type[DeclarativeBase]) -> str:
+    """Return the source code of ORM classes for the LM prompt.
+
+    Extracts source code via ``inspect.getsource`` for every mapped class
+    registered under *base*.  The sources are concatenated separated by
+    blank lines.
+    """
+    sources = [inspect.getsource(cls) for cls in base.__subclasses__()]
+    return "\n\n".join(sources)
+
+
+def _render_symbols(descriptions: dict[str, str]) -> str:
+    """Format the symbol descriptions dict as a Markdown bullet list."""
+    return "\n".join(f"- `{name}`: {desc}" for name, desc in descriptions.items())
+
+
+def _render_tools_summary(tools: list[Tool]) -> str:
+    """Render name + one-liner for each tool (empty string if no tools)."""
+    if not tools:
+        return ""
+    return "\n".join(f"- `{t.name}`: {t.short_description}" for t in tools)
+
+
+def _check_markers(source: str) -> None:
+    """Warn for each required Jinja variable missing from the raw template source."""
+    for marker in _REQUIRED_MARKERS:
+        if not re.search(r"\{\{\s*" + marker + r"\s*\}\}", source):
+            warnings.warn(
+                f"Prompt template is missing the `{{{{ {marker} }}}}` variable; "
+                "the agent may behave unpredictably.",
+                LLMAlchemyPromptWarning,
+                stacklevel=2,
+            )
+
+
+def render(
+    base: type[DeclarativeBase],
+    tools: list[Tool],
+    descriptions: dict[str, str],
+    template: str | Path | None = None,
+) -> str:
+    """Build the system instruction for the LM with all context parts.
+
+    Args:
+        base: The declarative base describing the schema.
+        tools: User-provided tools registered for this run.
+        descriptions: ``{name: description}`` of every namespace symbol,
+            as returned by ``_init_namespace`` in ``agent.py``.
+        template: A Jinja template source string, a ``Path`` to a template
+            file, or ``None`` to use the shipped default.
+    """
+    if template is None:
+        path: Path = _TEMPLATE_PATH
+        source = path.read_text()
+        _check_markers(source)
+        return render_template(
+            template=source,
+            SCHEMA=_render_schema_source(base=base),
+            SYMBOLS=_render_symbols(descriptions),
+            TOOLS=_render_tools_summary(tools),
+        )
+    source = template.read_text() if isinstance(template, Path) else template
+    _check_markers(source)
+    return render_template(
+        template=source,
+        SCHEMA=_render_schema_source(base=base),
+        SYMBOLS=_render_symbols(descriptions),
+        TOOLS=_render_tools_summary(tools),
+    )

llmalchemy/database.py

@@ -0,0 +1,62 @@
+"""Contains the utilities that access or modify the database."""
+
+import weakref
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session
+
+
+def deserialize(data: dict[str, list[dict]], base: type[DeclarativeBase]) -> Session:
+    """Unpack a JSON-serialised database state into an SQLAlchemy session.
+
+    Creates an in-memory SQLite database, issues ``Base.metadata.create_all``,
+    and populates every table from *data*.
+
+    Args:
+        data: Mapping of ``{table_name: [row_dict, ...]}``.
+        base: The declarative base whose metadata describes the schema.
+
+    Returns:
+        A ready-to-use SQLAlchemy ``Session`` bound to the in-memory database.
+    """
+    engine = create_engine("sqlite://")
+    base.metadata.create_all(engine)
+    session = Session(engine)
+    # Ensure the underlying sqlite3.Connection is closed when the session
+    # becomes unreachable, avoiding Python 3.13 ResourceWarnings.
+    weakref.finalize(session, engine.dispose)
+
+    # Build a lookup from table name to mapped class
+    cls_by_table: dict[str, type] = {}
+    for cls in base.__subclasses__():
+        table_name = cls.__tablename__ if hasattr(cls, "__tablename__") else cls.__table__.name
+        cls_by_table[table_name] = cls
+
+    for table_name, rows in data.items():
+        cls = cls_by_table.get(table_name)
+        if cls is None:
+            continue
+        for row in rows:
+            session.add(cls(**row))
+
+    session.commit()
+    return session
+
+
+def serialize(session: Session, base: type[DeclarativeBase]) -> dict[str, list[dict]]:
+    """Freeze the current database state into a JSON-serialisable dict.
+
+    Args:
+        session: The active session to read from.
+        base: The declarative base whose metadata describes the schema.
+
+    Returns:
+        ``{table_name: [row_dict, ...]}`` for every table in the schema.
+    """
+    result: dict[str, list[dict]] = {}
+    for cls in base.__subclasses__():
+        table_name = cls.__tablename__ if hasattr(cls, "__tablename__") else cls.__table__.name
+        columns = [c.key for c in cls.__table__.columns]
+        rows = session.query(cls).all()
+        result[table_name] = [{col: getattr(row, col) for col in columns} for row in rows]
+    return result

llmalchemy/prompt.jinja

@@ -0,0 +1,22 @@
+You are an expert assistant with access to a relational database containing the user's project.
+You can interact with the database using Python code and SQLAlchemy.
+
+# Guidelines
+- **Code Execution**: Run Python code to query or modify the database. Use `print()` to inspect results.
+- **Persistence**: The Python namespace is persistent. Imports and variables carry over between cells.
+- **Efficiency**: Keep `print()` statements concise. Avoid redundant imports or session initialization.
+- **Iteration**: Use the execution output (sent as an automatic user message) to decide if you need to run more code or provide a final answer.
+{% if TOOLS %}- **Tools**: Several tools are available in your namespace. Use `print(disclose(name))` to discover a tool's full signature and docstring before calling it.{% endif %}
+
+# Database Schema
+```python
+{{ SCHEMA }}
+```
+
+# Available Symbols
+The following symbols are pre-loaded in your namespace:
+{{ SYMBOLS }}
+{% if TOOLS %}
+# Available Tools
+{{ TOOLS }}
+{% endif %}

llmalchemy/tools.py

@@ -0,0 +1,78 @@
+"""Logic to expose functions to the model."""
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class HasMetadata(Protocol):
+    """Protocol for objects that have __name__ and __doc__."""
+
+    __name__: str
+    __doc__: str | None
+
+
+@dataclass(frozen=True)
+class Tool:
+    """Metadata wrapper around a user-provided function.
+
+    Attributes:
+        fn: The original callable.
+        name: Function name (used as the namespace key).
+        short_description: First line of the docstring.
+        full_description: Full signature and docstring for discovery.
+    """
+
+    fn: Callable[..., Any]
+    name: str
+    short_description: str
+    full_description: str
+
+    @classmethod
+    def from_function(cls, fn: Any) -> "Tool":
+        """Build a ``Tool`` from a plain function."""
+        name = getattr(fn, "__name__", "unknown")
+        doc = inspect.cleandoc(getattr(fn, "__doc__", "") or "")
+        short = doc.split("\n", 1)[0] if doc else ""
+        sig = inspect.signature(fn)
+        full = f'def {name}{sig}:\n    """{doc}"""' if doc else f"def {name}{sig}:"
+        return cls(fn=fn, name=name, short_description=short, full_description=full)
+
+
+def tool(fn: Any) -> Tool:
+    """Decorator that turns a function into a ``Tool``."""
+    return Tool.from_function(fn)
+
+
+def make_disclose_fn(tools: list[Tool]) -> Callable:
+    """Build the ``disclose`` closure injected into the agent namespace.
+
+    This is a *closure factory*: it builds ``lookup`` once from *tools*,
+    then returns an inner function that captures ``lookup``.  Each call to
+    ``make_disclose_fn`` produces a fresh ``disclose`` bound to exactly the
+    tools registered for that ``run()`` invocation.
+
+    Args:
+        tools: The list of tools registered for this run.
+
+    Returns:
+        A callable ``(name: str) -> str``.
+    """
+    lookup = {t.name: t.full_description for t in tools}
+
+    def disclose(name: str) -> str:
+        """Reveal the full signature and docstring of a tool.
+
+        Args:
+            name: The tool name to look up.
+
+        Returns:
+            The full description string, or an error message if not found.
+        """
+        if name in lookup:
+            return lookup[name]
+        available = ", ".join(lookup) or "(none)"
+        return f"Unknown tool: {name!r}. Available tools: {available}"
+
+    return disclose

llmalchemy-1.4.1.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.3
+Name: llmalchemy
+Version: 1.4.1
+Summary: A full-access agent pattern.
+Author: Ignacio Llorca
+Author-email: Ignacio Llorca <nllorca@proton.me>
+License: MIT
+Requires-Dist: lmdk
+Requires-Dist: sqlalchemy
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+![banner](assets/banner.png)
+
+Every **new operation** you want to allow a user to perform on your application's data model means **new logic** (backend) and a **new screen** (frontend). Then, the user has to learn how to perform that particular operation.
+
+`llmalchemy` removes that layer. Hand an LM your ORM schema and a sandboxed Python environment. **The user requests any operation through natural language**. The agent composes its own queries and transformations as code in a single turn.
+
+**You do not need to define a thousand GUIs for each possible action, nor a thousand tools for the LM to leverage** (GET X, POST Y, etc.): the abstraction to freely manipulate the data model already exists: it is SQL. ORM and python add an infinite number of possibilities on top.
+
+![gui-vs-nli](assets/gui-vs-nli.png)
+
+**Read the complete motivation / reasoning in the [whitepaper](#whitepaper-why-llmalchemy)**
+
+## Installation
+
+`uv add llmalchemy`
+
+## Usage
+
+The only thing you need to define upfront is your database schema through an sqlalchemy declarative base:
+```python
+from llmalchemy.agent import State, run
+from lmdk import UserMessage
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+class Base(DeclarativeBase): ...
+
+class Author(Base):
+    """An author who can write many books."""
+
+    __tablename__ = "authors"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(120))
+
+    books: Mapped[list["Book"]] = relationship(back_populates="author")
+
+
+class Book(Base):
+    """A book belonging to a single author."""
+
+    __tablename__ = "books"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    title: Mapped[str] = mapped_column(String(200))
+    author_id: Mapped[int] = mapped_column(ForeignKey("authors.id"))
+
+    author: Mapped["Author"] = relationship(back_populates="books")
+
+
+model = "vertex:gemini-3-flash-preview"
+```
+
+For the minimal run, append the first message to the conversation and simply iterate over the `run` call.
+You will receive `Events` with the messages and code results performed by the agent, together with precise signals indicating the agents loop state (waiting for the LM completion, executing code, etc.):
+
+```python
+state = State()
+state.messages.append(UserMessage("Add authors Tolkien and Dhalia de la Cerda, and two books for each."))
+
+for event in run(state=state, base=Base, model=model):
+    print(event)
+```
+
+Example output (abbreviated):
+```text
+SystemInstructionEvent(content='You are a coding agent... SCHEMA: class Author...')
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message="I'll add the authors and their books.", code="a1 = Author(name='J.R.R. Tolkien')\na2 = Author(name='Dhalia de la Cerda')\nsession.add_all([a1, a2])\nsession.flush()\nsession.add_all([\n    Book(title='The Hobbit', author_id=a1.id),\n    Book(title='The Lord of the Rings', author_id=a1.id),\n    Book(title='Desde los zulos', author_id=a2.id),\n    Book(title='Perras de reserva', author_id=a2.id),\n])\nsession.commit()\nprint('ok')"))
+SignalEvent(signal=<Signal.VALIDATION: 'VALIDATION'>)
+SignalEvent(signal=<Signal.EXECUTION: 'EXECUTION'>)
+MessageEvent(message=UserMessage(content='Execution result:\nok\n'))
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message='Done — added Tolkien and Dhalia de la Cerda with two books each.', code=''))
+```
+
+The `state` persists across calls, just append a new `UserMessage` and call `run()` again to continue the conversation.
+
+<details>
+<summary>Custom tools</summary>
+You can define any pre-built function that you want the agent to have access to.
+These can modify the database or do something completely different, like performing math operations or calling another API.
+
+```python
+from sqlalchemy.orm import Session
+from llmalchemy.tools import tool
+
+@tool
+def get_author_catalog(author: str, session: Session) -> list[str]:
+    """List all book titles for the given author."""
+    obj = session.query(Author).filter(Author.name == author).first()
+    return [b.title for b in obj.books] if obj else []
+
+state.messages.append(UserMessage("what's the catalog for Dhalia de la Cerda?"))
+for event in run(state=state, base=Base, model=model, tools=[get_author_catalog]):
+    print(event)
+```
+
+Example output (abbreviated):
+```text
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message='Let me check the tool signature first.', code="disclose('get_author_catalog')"))
+SignalEvent(signal=<Signal.EXECUTION: 'EXECUTION'>)
+MessageEvent(message=UserMessage(content="Execution result:\nget_author_catalog(author: str, session: Session) -> list[str]\nList all book titles for the given author.\n"))
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message='', code="print(get_author_catalog('Dhalia de la Cerda', session))"))
+SignalEvent(signal=<Signal.EXECUTION: 'EXECUTION'>)
+MessageEvent(message=UserMessage(content="Execution result:\n['Desde los zulos', 'Perras de reserva']\n"))
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message="Dhalia de la Cerda's catalog: 'Desde los zulos' and 'Perras de reserva'.", code=''))
+```
+
+Only the tool name and first docstring line are shown to the agent up-front.
+The agent calls `disclose("get_author_catalog")` to inspect the full signature on demand.
+</details>
+
+<details>
+<summary>Allowed imports</summary>
+For safety, no imports are allowed inside agent-generated code.
+Whitelist any stdlib or third-party module the agent may need.
+
+```python
+state.messages.append(UserMessage("what day is today?"))
+for event in run( state=state, base=Base, model=model, allowed_imports=["datetime"]):
+    print(event)
+```
+
+Example output (abbreviated):
+```text
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message='', code='import datetime\nprint(datetime.date.today().isoformat())'))
+SignalEvent(signal=<Signal.VALIDATION: 'VALIDATION'>)
+SignalEvent(signal=<Signal.EXECUTION: 'EXECUTION'>)
+MessageEvent(message=UserMessage(content='Execution result:\n2026-04-21\n'))
+SignalEvent(signal=<Signal.COMPLETION: 'COMPLETION'>)
+MessageEvent(message=AssistantMessage(message='Today is 2026-04-21.', code=''))
+```
+
+If the agent tries to import something not whitelisted, validation fails and it gets a second chance:
+```text
+MessageEvent(message=UserMessage(content="Code rejected: import of 'os' is not allowed"))
+```
+</details>
+
+<details>
+<summary>Custom system prompt</summary>
+You can pass a Jinja template to override the default one (see `src/llmalchemy/prompt.jinja`).
+It is recommended that the template contains vars {{ SCHEMA }}, {{ SYMBOLS }} and {{ TOOLS }}.
+
+```python
+prompt = """Write python code to answer user requests. You have access to {{ SCHEMA }}, {{ SYMBOLS }} and {{ TOOLS }}"""
+for event in run(
+    state=state,
+    base=Base,
+    model=model,
+    prompt_template="path/to/prompt.jinja",
+):
+    print(event)
+```
+
+The emitted events are the same as in the minimal example; only the `SystemInstructionEvent` content changes to reflect your custom template:
+```text
+SystemInstructionEvent(content='Write python code to answer user requests. You have access to <schema...>, <symbols...> and <tools...>')
+```
+</details>
+
+<details>
+<summary>Output extensions</summary>
+By default, the agent responds with a `message` for the user and optional `code` to perform actions.
+You can specify any additional fields for the LM to fill.
+
+```python
+from pydantic import BaseModel, Field
+
+class Reasoning(BaseModel):
+    thoughts: str = Field(description="Scratchpad before answering.")
+    confidence: float = Field(description="0..1 confidence score.")
+
+for event in run(
+    state=state,
+    base=Base,
+    model=model,
+    output_extensions=Reasoning,
+):
+    print(event)
+# Extra fields ride along on the yielded AssistantMessage for you to consume:
+#
+# MessageEvent(message=AssistantMessage(
+#     thoughts='The user asked X; I should query Y then aggregate by Z.',
+#     confidence=0.82,
+#     message='Here are the results ...',
+#     code='...',
+# ))
+```
+</details>
+
+## How it works
+In short: **user input → LM generates SQLAlchemy code → validate → execute → return results to LM → repeat until done**
+
+```mermaid
+flowchart TD
+    Start([run]) --> Init[Initialize session,<br/>namespace, system prompt]
+    Init --> Complete[LM completion<br/>→ message + code]
+    Complete --> HasCode{code?}
+    HasCode -- no --> End([return to user])
+    HasCode -- yes --> MaxLoops{loops ≥ MAX?}
+    MaxLoops -- yes --> Exceeded[signal: EXCEEDED] --> End
+    MaxLoops -- no --> Validate[validate code]
+    Validate --> Valid{valid?}
+    Valid -- no --> Reject[append 'Code rejected'<br/>user message]
+    Reject --> Complete
+    Valid -- yes --> Execute[execute code<br/>in namespace]
+    Execute --> Result[append 'Execution result'<br/>user message]
+    Result --> Complete
+```
+
+1. **Schema as context** (`context.py`): The source code of your ORM classes is extracted via `inspect.getsource` and rendered into a Jinja system prompt alongside available symbols and tools.
+
+2. **Agentic loop** (`agent.py`): The LM produces structured output — a message and optional Python code. If code is present, it's validated, executed, and the result is fed back as a user message. The loop continues until the LM responds without code or hits `MAX_LOOPS`.
+
+3. **Sandboxed execution** (`code.py`): An AST pass blocks dangerous builtins (`exec`, `eval`, `open`…), forbidden modules (`os`, `subprocess`…), dangerous dunder access, and enforces an import whitelist. Safe code runs in a persistent namespace with stdout captured.
+
+4. **Optional tools** (`tools.py`): Developers can register custom functions with the `@tool` decorator. Only tool names and one-liners appear in the prompt — the LM calls `disclose(name)` to see full signatures on demand, keeping the context window lean.
+
+## Whitepaper (why `llmalchemy`)
+
+### Tool calling hits a wall
+
+The standard agentic pattern is function calling: define tools, let the LM pick one, read the result, repeat. This is clean and safe, but it doesn't scale.
+
+Real applications have complex data models. To give the LM meaningful access you end up writing dozens of tools, each one crowding the context window. Every compound operation (filter, then aggregate, then compare) either needs its own dedicated tool or forces the agent to chain calls across multiple LM completions — slow and expensive. And you become the bottleneck: every new user need is a new tool to design, implement, test and document.
+
+### Code as the action space
+
+Research shows that letting LMs write and execute code instead of picking from a discrete set of tools produces stronger agents[[1](https://arxiv.org/abs/2402.01030)][[2](https://arxiv.org/pdf/2401.00812)][[3](https://arxiv.org/pdf/2411.01747)][[4](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)][[5](https://blog.cloudflare.com/code-mode/)]. Code gives the model composition (chain operations in one turn), control flow (loops, conditionals, error handling), and self-extension (define helper functions that persist in the namespace). A single code block can do what would otherwise take a long chain of tool calls.
+
+But code execution alone doesn't solve the data access problem. The LM still needs some interface to read and modify application state. You're back to writing wrapper functions — unless the right abstraction already exists.
+
+### Relational algebra is the interface you don't have to build
+
+And it does. Relational algebra is a solved discipline: decades of refinement behind optimal ways of organizing and querying structured data. SQL databases implement it. ORMs like SQLAlchemy wrap it in the same Python the LM is already writing.
+
+By placing an ORM session and the model classes in the agent's execution namespace, `llmalchemy` gives the LM full, structured access to the data without a single hand-crafted tool. The developer defines the schema once — which they'd do anyway. The LM handles everything else.
+
+### What this means for applications
+
+Traditional software requires two layers of work on top of the data model:
+
+1. **Business logic** (backend) — functions and endpoints for every operation users might need.
+2. **UI workflows** (frontend) — screens, forms and click sequences to expose those operations.
+
+Both layers grow with the complexity of the data model and the operations pipelines that we want to allow for the user.
+
+With `llmalchemy`, the developer defines the schema and optionally a handful of tools for things that genuinely require custom logic (sending emails, calling external APIs, very complex workflows). Everything else — every query, every data transformation, every "find all X where Y and then update Z" — the LM composes on the fly.
+
+For users, this replaces navigating menus and filling forms with describing what they want. It removes the mismatch between what the user is thinking and the rigid paths a GUI offers.
+
+### Beyond file systems
+
+Today's coding agents (Opencode, Pi, Claude Code) prove that LMs can navigate file structures effectively with tools as simple as `bash`, `read`, `write` and `edit`. But file systems are structurally simple: trees of named nodes with blob contents.
+
+Application data is a different beast. Dozens of entity types, foreign keys, many-to-many relationships, constraints, cascading dependencies. Relational data is orders of magnitude richer than a directory tree. The ORM gives the LM the right abstraction: it thinks in terms of entities, relationships and queries rather than raw files.
+
+## Development
+
+This package uses [`lmdk`](https://github.com/nachollorca/lmdk) to inference LLMs.
+
+### Structure
+```
+src/llmalchemy/
+├── agent.py      # Entrypoint for the agentic loop
+├── code.py       # Sandboxed python env on which to run the agent requested code
+├── context.py    # Utils to engineer the context passed to the agent
+├── database.py    # Utils that access or modify the database
+├── prompt.jinja  # Default system instruction template
+└── tools.py      # Logic to expose functions to the model
+```
+
+### Tooling
+We use `just` for development tasks. Use:
+- `just sync`: Updates lockfile and syncs environment.
+- `just format`: Lints and formats with `ruff`.
+- `just check-types`: Static analysis with `ty`.
+- `just check-complexity`: Cyclomatic complexity checks with `complexipy`.
+- `just test`: Runs pytest with 90% coverage threshold.
+
+See [`justfile`](justfile) for a complete list of dev commands.
+
+### Contribute
+1. **Hooks**: Install pre-commit hooks via `just install-hooks`. PRs will fail CI if linting/formatting is not applied.
+2. **Issues**: Open an issue first using the default template.
+3. **PRs**: Link your PR to the relevant issue using the PR template.
+
+## License
+MIT
+
+_Made with [`mold`](https://github.com/nachollorca/mold) template_

llmalchemy-1.4.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+llmalchemy/__init__.py,sha256=N3hmY3mE-9vX17gxbcB7If4loAW_PwrC2QI7o4MCdXU,107
+llmalchemy/agent.py,sha256=zhha5LzYwCsENpvmCrtt_CxMmad72IOoTwRW7wDqMNs,9099
+llmalchemy/code.py,sha256=2_qNfSdOI-1n-vQRzTb6Jd0BmY9GpTLzfwWha9Nm9YI,4343
+llmalchemy/context.py,sha256=IswICwyvDi7gs2yVsiNqJK_lWyAKgu8FhYr7W1Iw9_Q,3112
+llmalchemy/database.py,sha256=Zm-GZWL9j0Rj-RI0Ac1PtZOqljmn95nzy2Vic5Zd4GU,2261
+llmalchemy/prompt.jinja,sha256=PkYErqZvocsQAr3GKyhDKL4yJOZ4k52mL8KtbAVlRMk,1011
+llmalchemy/tools.py,sha256=jfw0R9mOODzmkyjHCfhtEzbAHsfuVSSxOeOuO4OTVK0,2410
+llmalchemy-1.4.1.dist-info/WHEEL,sha256=q5IF0q2xCp3ktUFRCVWsQLjl2ChNlWXBJtnI1LCGdJ8,80
+llmalchemy-1.4.1.dist-info/METADATA,sha256=3wodW6bZsJ5Vwz4LS-gykKPuuEfE16PI_GGdNmyeO_s,15429
+llmalchemy-1.4.1.dist-info/RECORD,,

llmalchemy-1.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.8
+Root-Is-Purelib: true
+Tag: py3-none-any