llmalchemy 2.0.0__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: llmalchemy
-Version: 2.0.0
+Version: 2.1.0
 Summary: A full-access agent pattern.
 Author: Ignacio Llorca
 Author-email: Ignacio Llorca <nllorca@proton.me>

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

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

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

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

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

@@ -202,6 +202,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.
 
@@ -223,6 +224,9 @@ def run(
             - ``SYMBOLS``: used to show ageent all pre-loaded namespace symbols.
             - ``TOOLS``: usedf 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 +242,7 @@ def run(
             allowed_imports,
             prompt_template,
             output_extensions,
+            referenceable_tables,
         )
 
 
@@ -251,6 +256,7 @@ 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
@@ -258,7 +264,9 @@ def _run(
     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)
+    system_instruction = render(
+        base, tools, descriptions, prompt_template, allowed_imports, referenceable_tables
+    )
     yield SystemInstructionEvent(system_instruction)
     before = serialize(session, base)
 
@@ -268,6 +276,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-2.1.0}/src/llmalchemy/context.py

@@ -51,6 +51,29 @@ def _render_imports(allowed_imports: list[str]) -> str:
     return f"Only these modules may be imported: {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:
     """Warn for each required Jinja variable missing from the raw template source."""
     for marker in _REQUIRED_MARKERS:
@@ -69,6 +92,7 @@ def render(
     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.
 
@@ -81,19 +105,14 @@ def render(
             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,
@@ -101,4 +120,5 @@ def render(
         SYMBOLS=_render_symbols(descriptions),
         TOOLS=_render_tools_summary(tools),
         IMPORTS=_render_imports(allowed_imports or []),
+        REFERENCES=_render_references(base, referenceable_tables),
     )

{llmalchemy-2.0.0 → llmalchemy-2.1.0}/src/llmalchemy/prompt.jinja

@@ -4,10 +4,11 @@ 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 REFERENCES %}- **References**: {{ REFERENCES }}{% endif %}
+- **Efficiency**: Avoid redundant imports, session initialization and repeated prints.
+- **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.
+- **Persistence**: the Python namespace (variables, imports, ...) carry over between cells only within the same turn. A new user message means a newly initialized namespace.
 {% 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.