llmalchemy 2.0.0__tar.gz → 3.0.0__tar.gz

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: llmalchemy
-Version: 2.0.0
+Version: 3.0.0
 Summary: A full-access agent pattern.
 Author: Ignacio Llorca
 Author-email: Ignacio Llorca <nllorca@proton.me>
@@ -178,10 +178,10 @@ MessageEvent(message=UserMessage(content="Code rejected: Forbidden import: os"))
 <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 }}, {{ TOOLS }} and {{ IMPORTS }}.
+It is recommended that the template contains vars {{ SCHEMA }}, {{ TOOLS }} and {{ IMPORTS }}.
 
 ```python
-prompt = """Write python code to answer user requests. You have access to {{ SCHEMA }}, {{ SYMBOLS }} and {{ TOOLS }}."""
+prompt = """Write python code to answer user requests. You have access to {{ SCHEMA }} and {{ TOOLS }}."""
 for event in run(
     session=session,
     messages=messages,
@@ -195,7 +195,7 @@ for event in run(
 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...>')
+SystemInstructionEvent(content='Write python code to answer user requests. You have access to <schema...> and <tools...>')
 ```
 
 </details>

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/README.md

@@ -164,10 +164,10 @@ MessageEvent(message=UserMessage(content="Code rejected: Forbidden import: os"))
 <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 }}, {{ TOOLS }} and {{ IMPORTS }}.
+It is recommended that the template contains vars {{ SCHEMA }}, {{ TOOLS }} and {{ IMPORTS }}.
 
 ```python
-prompt = """Write python code to answer user requests. You have access to {{ SCHEMA }}, {{ SYMBOLS }} and {{ TOOLS }}."""
+prompt = """Write python code to answer user requests. You have access to {{ SCHEMA }} and {{ TOOLS }}."""
 for event in run(
     session=session,
     messages=messages,
@@ -181,7 +181,7 @@ for event in run(
 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...>')
+SystemInstructionEvent(content='Write python code to answer user requests. You have access to <schema...> and <tools...>')
 ```
 
 </details>

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "llmalchemy"
-version = "2.0.0"
+version = "3.0.0"
 description = "A full-access agent pattern."
 requires-python = ">=3.13"
 readme = "README.md"

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "llmalchemy"
-version = "2.0.0"
+version = "3.0.0"
 description = "A full-access agent pattern."
 requires-python = ">=3.13"
 license = { text = "MIT" }

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/src/llmalchemy/agent.py

@@ -145,51 +145,28 @@ def _init_namespace(
     session: Session,
     base: type[DeclarativeBase],
     tools: list[Tool],
-) -> tuple[dict, dict[str, str]]:
+) -> dict:
     """Build a fresh code execution namespace for one run.
 
     Injects ``session``, ORM model classes, association tables, tool functions,
     and ``disclose``.
-
-    Returns:
-        The namespace, and 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``.
     """
     namespace: dict = {}
-    descriptions: dict[str, str] = {}
 
     namespace["session"] = session
-    descriptions["session"] = "a `sqlalchemy.orm.Session` connected to the database."
 
-    orm_classes = mapped_classes(base)
-    for cls in orm_classes:
+    for cls in mapped_classes(base):
         namespace[cls.__name__] = cls
-    if orm_classes:
-        names = ", ".join(cls.__name__ for cls in orm_classes)
-        descriptions[names] = "ORM model classes (see schema above)."
-
-    tables = association_tables(base)
-    namespace.update(tables)
-    if tables:
-        names = ", ".join(tables)
-        descriptions[names] = (
-            "`sqlalchemy.Table` association objects for many-to-many junctions,"
-            " usable directly (e.g. `session.execute(insert(table), rows)`)."
-        )
+
+    namespace.update(association_tables(base))
 
     for t in tools:
         namespace[t.name] = t.fn
 
     if tools:
         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 namespace, descriptions
+    return namespace
 
 
 def run(
@@ -202,6 +179,7 @@ def run(
     allowed_imports: list[str] | None = None,
     prompt_template: str | Path | None = None,
     output_extensions: type[BaseModel] | None = None,
+    referenceable_tables: list[str] | None = None,
 ) -> Iterator[Event]:
     """Execute the agentic loop.
 
@@ -219,10 +197,12 @@ def run(
         output_extensions: Optional Pydantic model to force in the LM structured output.
         thinking_effort: Level of thinking for provider-native reasoning tokens.
         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.
+            - ``SCHEMA``: used to show the agent the source code of the schema module.
+            - ``TOOLS``: used to show the agent tool names + short descriptions.
             - ``IMPORTS``: used to show the agent which modules it may import.
+        referenceable_tables: Schema table names the agent may cite inline in its
+            messages, e.g. ``[authors:1]``. Defaults to ``None`` (disabled);
+            unknown names raise ``ValueError``.
 
     Yields:
         ``Event``: system instruction, loop signals, and conversation messages.
@@ -238,6 +218,7 @@ def run(
             allowed_imports,
             prompt_template,
             output_extensions,
+            referenceable_tables,
         )
 
 
@@ -251,14 +232,15 @@ def _run(
     allowed_imports: list[str] | None,
     prompt_template: str | Path | None,
     output_extensions: type[BaseModel] | None,
+    referenceable_tables: list[str] | None = None,
 ) -> Iterator[Event]:
     """Agentic loop body (see :func:`run`)."""
     # Initialize everything
     tools = tools or []
     allowed_imports = ["sqlalchemy"] if allowed_imports is None else allowed_imports
     output_schema = _build_output_schema(output_extensions)
-    namespace, descriptions = _init_namespace(session, base, tools)
-    system_instruction = render(base, tools, descriptions, prompt_template, allowed_imports)
+    namespace = _init_namespace(session, base, tools)
+    system_instruction = render(base, tools, prompt_template, allowed_imports, referenceable_tables)
     yield SystemInstructionEvent(system_instruction)
     before = serialize(session, base)
 
@@ -268,6 +250,8 @@ def _run(
     )
     code = output.code
 
+    # Note: agent can inline cite tables, we should verify that they are valid (issue 30)
+
     # Loop until model is over with the task
     loops = 0
     while code:

{llmalchemy-2.0.0 → llmalchemy-3.0.0}/src/llmalchemy/context.py

@@ -2,18 +2,18 @@
 
 import inspect
 import re
+import sys
 import warnings
 from pathlib import Path
 
 from lmdk import render_template
 from sqlalchemy.orm import DeclarativeBase
 
-from .database import mapped_classes
 from .tools import Tool
 
 _TEMPLATE_PATH = Path(__file__).parent / "prompt.jinja"
 
-_REQUIRED_MARKERS = ("SCHEMA", "SYMBOLS", "TOOLS", "IMPORTS")
+_REQUIRED_MARKERS = ("SCHEMA", "TOOLS", "IMPORTS")
 
 
 class LLMAlchemyPromptWarning(UserWarning):
@@ -21,19 +21,12 @@ class LLMAlchemyPromptWarning(UserWarning):
 
 
 def _render_schema_source(base: type[DeclarativeBase]) -> str:
-    """Return the source code of ORM classes for the LM prompt.
+    """Return the source of the module defining *base* 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.
+    The whole module is shown (enums, junction tables, mixins, constraints),
+    so keep implementation details such as ORM hooks in a separate module.
     """
-    sources = [inspect.getsource(cls) for cls in mapped_classes(base)]
-    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())
+    return inspect.getsource(sys.modules[base.__module__])
 
 
 def _render_tools_summary(tools: list[Tool]) -> str:
@@ -46,9 +39,34 @@ def _render_tools_summary(tools: list[Tool]) -> str:
 def _render_imports(allowed_imports: list[str]) -> str:
     """Render the import policy as one sentence."""
     if not allowed_imports:
-        return "`import` statements are forbidden. Use only the pre-loaded symbols listed below."
+        return (
+            "`import` statements are forbidden. Use only the symbols pre-loaded in your namespace."
+        )
     modules = ", ".join(f"`{m}`" for m in allowed_imports)
-    return f"Only these modules may be imported: {modules}."
+    return f"Module imports are forbidden, with exception of: {modules}."
+
+
+def _render_references(base: type[DeclarativeBase], referenceable_tables: list[str] | None) -> str:
+    """Render the row-reference instruction for the allowed tables.
+
+    Table names are validated against the schema so a typo raises instead of
+    silently letting the agent cite a table that does not exist.
+    """
+    if not referenceable_tables:
+        return ""
+    known = base.metadata.tables
+    unknown = [name for name in referenceable_tables if name not in known]
+    if unknown:
+        raise ValueError(
+            f"Unknown referenceable table(s): {', '.join(unknown)}. "
+            f"Available tables: {', '.join(sorted(known))}."
+        )
+    names = ", ".join(f"`{name}`" for name in referenceable_tables)
+    return (
+        f"You can reference specific rows in {names} by inlining "
+        f"`[{referenceable_tables[0]}:row_pk]` in your message to the user, "
+        "where `row_pk` is the row's primary key value."
+    )
 
 
 def _check_markers(source: str) -> None:
@@ -66,39 +84,32 @@ def _check_markers(source: str) -> None:
 def render(
     base: type[DeclarativeBase],
     tools: list[Tool],
-    descriptions: dict[str, str],
     template: str | Path | None = None,
     allowed_imports: list[str] | None = None,
+    referenceable_tables: list[str] | 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.
         allowed_imports: Modules the agent may import. ``None`` or an empty
             list means imports are forbidden.
+        referenceable_tables: Schema table names the agent may cite inline,
+            e.g. ``[authors:1]``. ``None`` means citations are disabled.
     """
     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),
-            IMPORTS=_render_imports(allowed_imports or []),
-        )
-    source = template.read_text() if isinstance(template, Path) else template
+    else:
+        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),
         IMPORTS=_render_imports(allowed_imports or []),
+        REFERENCES=_render_references(base, referenceable_tables),
     )

llmalchemy-3.0.0/src/llmalchemy/prompt.jinja

@@ -0,0 +1,25 @@
+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.
+Your task is to navigate and edit the project to fulfill the user's requests.
+
+# Guidelines
+- **Code Execution**: Run Python code to query or modify the database. Use `print()` to inspect results.
+- **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 to end the turn.
+- **Efficiency**: Keep `print()` statements concise, avoid redundant imports or unnecessary checks.
+- **Persistence**: the Python namespace (variables, imports, ...) carry over between cells only within the same turn. A new user message means a newly initialized namespace.
+- **Imports**: {{ IMPORTS }}
+{% if REFERENCES %}- **References**: {{ REFERENCES }}{% endif %}
+{% if TOOLS %}- **Tools**: Several tools (pre-built python functions) 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 }}
+```
+
+Your namespace is pre-loaded with `session` and every class and association table shown above — no need to import or redefine them.
+
+{% if TOOLS %}
+# Available Tools
+The tools below are also pre-loaded in the namespace.
+{{ TOOLS }}
+{% endif %}

llmalchemy-2.0.0/src/llmalchemy/prompt.jinja

@@ -1,27 +0,0 @@
-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.
-- **Imports**: {{ IMPORTS }}
-- **Persistence**: Variables (and any allowed imports) carry over between cells, until the user sends a new message.
-- **Printing**: Keep `print()` statements concise, but print anything you may need in a later turn (ids, key values, short findings).
-- **Efficiency**: 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 %}
-- **Transactions**: the SQLAlchemy `session` is also shared by every cell, nothing is committed or rolled back for you.
-  - Uncommitted work piles up across cells.
-  - A code execution that raises halfway leaves the part that already ran pending.
-
-# Database Schema
-```python
-{{ SCHEMA }}
-```
-
-# Available Symbols
-The following symbols are pre-loaded in your namespace:
-{{ SYMBOLS }}
-{% if TOOLS %}
-# Available Tools
-{{ TOOLS }}
-{% endif %}