makefile-agent 0.3.0__py3-none-any.whl

make_agent/tools.py

@@ -0,0 +1,193 @@
+"""Tool schema builder and executor for the make-agent.
+
+Converts parsed Makefile rules into OpenAI-compatible tool definitions and
+executes them by injecting parameters safely before invoking ``make``.
+
+Parameter injection
+-------------------
+For each tool call, values are injected in two complementary ways:
+
+1. **Temp file** (``PARAM_FILE``): Every parameter value is written to a
+   temporary file.  Make receives ``PARAM_FILE=/tmp/...`` so recipes can
+   read arbitrary content::
+
+       write-file:
+           @cat "$(PARAM_FILE)" > "$(DEST)"
+
+2. **params.mk** (``PARAM``): For single-line values, a temporary
+   ``params.mk`` is also written with ``PARAM = <value>`` (``$`` signs
+   escaped as ``$$``) and loaded with ``-f params.mk``.  Recipes that
+   reference ``$(PARAM)`` directly continue to work for simple values::
+
+       greet:
+           @echo "Hello, $(NAME)!"
+
+The ``_FILE`` suffix form works for **all** values including multiline
+text; the bare form is a convenience for the common single-line case.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from make_agent.parser import Makefile, Param
+
+logger = logging.getLogger(__name__)
+
+
+_VALID_MAKE_VAR_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _is_valid_make_var_name(name: str) -> bool:
+    return bool(_VALID_MAKE_VAR_NAME_RE.fullmatch(name))
+
+
+def _escape_make_value(value: str) -> str:
+    """Escape *value* for use on the right-hand side of a Make ``=`` assignment.
+
+    Only ``$`` needs escaping: ``$`` → ``$$``.  Everything else (quotes,
+    backslashes, spaces) is safe in a Make variable value.
+    """
+    return value.replace("$", "$$")
+
+
+def format_tool_result(stdout: str, stderr: str, exit_code: int | None, max_output: int = 0) -> str:
+    """Serialise tool output as a JSON string for the LLM.
+
+    *max_output* limits how many characters of *stdout* and *stderr* are kept
+    (each stream capped independently).  When a stream is longer, the excess is
+    dropped and an ``omitted_chars`` key is added so the LLM knows it received
+    a partial result.  ``0`` means no limit.
+    """
+    omitted = 0
+    if max_output > 0 and len(stdout) > max_output:
+        omitted += len(stdout) - max_output
+        stdout = stdout[:max_output]
+    if max_output > 0 and len(stderr) > max_output:
+        omitted += len(stderr) - max_output
+        stderr = stderr[:max_output]
+    result: dict[str, Any] = {"stdout": stdout, "stderr": stderr, "exit_code": exit_code}
+    if omitted:
+        result["omitted_chars"] = omitted
+    return json.dumps(result)
+
+
+def _param_schema(p: Param) -> dict[str, str]:
+    """Return the JSON Schema fragment for a single tool parameter."""
+    json_type = p.type if p.type in ("string", "number", "integer", "boolean") else "string"
+    return {"type": json_type, "description": p.description}
+
+
+def build_tools(makefile: Makefile) -> list[dict[str, Any]]:
+    """Return a list of OpenAI function-tool dicts for every rule that has a
+    ``# <tool>`` description block."""
+    tools = []
+    for rule in makefile.rules:
+        if rule.description is None:
+            continue
+        properties = {p.name: _param_schema(p) for p in rule.params}
+        tools.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": rule.target,
+                    "description": rule.description,
+                    "parameters": {
+                        "type": "object",
+                        "properties": properties,
+                        "required": [p.name for p in rule.params],
+                    },
+                },
+            }
+        )
+    return tools
+
+
+def run_tool(
+    target: str,
+    arguments: dict[str, Any],
+    makefile_path: Path,
+    timeout: int = 600,
+    max_output: int = 0,
+) -> str:
+    """Invoke ``make`` with safely injected parameters and return output as JSON.
+
+    Returns a JSON string with keys ``stdout``, ``stderr``, and ``exit_code``
+    (``null`` for framework-level errors such as timeout or OS failure).  When
+    *max_output* is non-zero and the stdout exceeds that limit, the output is
+    truncated and an ``omitted_chars`` key is added.
+
+    Every argument value is written to a temporary file; Make receives
+    ``PARAM_FILE=/tmp/...`` for each parameter.  For single-line values
+    that contain no newlines, a temporary ``params.mk`` is also written
+    with ``PARAM = <escaped-value>`` so recipes can use ``$(PARAM)``
+    directly without any quoting ceremony.
+
+    All temporary files are always removed after the subprocess exits.
+    """
+    tmp_files: list[Path] = []
+    try:
+        for k in arguments:
+            if not _is_valid_make_var_name(k):
+                return format_tool_result("", f"{k!r} is not a valid make variable name", None)
+
+        params_mk_lines: list[str] = []
+        make_vars: list[str] = []
+
+        for k, v in arguments.items():
+            # Normalise JSON primitives (int, float, bool) to str.
+            v_str = str(v)
+            # Always write a temp file for $(PARAM_FILE) access.
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                prefix=f"make-agent-{k}-",
+                suffix=".tmp",
+                delete=False,
+            ) as tf:
+                tf.write(v_str)
+                file_path = Path(tf.name)
+            tmp_files.append(file_path)
+            make_vars.append(f"{k}_FILE={file_path}")
+
+            # Also provide $(PARAM) for single-line values via params.mk.
+            if "\n" not in v_str:
+                params_mk_lines.append(f"{k} = {_escape_make_value(v_str)}")
+
+        cmd: list[str] = ["make", "--no-print-directory"]
+
+        if params_mk_lines:
+            params_content = "\n".join(params_mk_lines) + "\n"
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                prefix="make-agent-params-",
+                suffix=".mk",
+                delete=False,
+            ) as tf:
+                tf.write(params_content)
+                params_mk = Path(tf.name)
+            tmp_files.append(params_mk)
+            cmd += ["-f", str(params_mk)]
+
+        cmd += ["-f", str(makefile_path), target] + make_vars
+
+        logger.debug(f"running tool with command: {' '.join(cmd)}")
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, stdin=subprocess.DEVNULL, timeout=timeout)
+            logger.debug(f"result of '{' '.join(cmd)}': exit {result.returncode}, stdout: {result.stdout!r}, stderr: {result.stderr!r}")
+        except subprocess.TimeoutExpired:
+            return format_tool_result("", f"tool '{target}' exceeded {timeout}s limit", None)
+        except OSError as e:
+            return format_tool_result("", f"failed to run make: {e}", None)
+        return format_tool_result(result.stdout, result.stderr, result.returncode, max_output)
+    finally:
+        for tmp in tmp_files:
+            try:
+                tmp.unlink()
+            except OSError:
+                pass

makefile_agent-0.3.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: makefile-agent
+Version: 0.3.0
+Summary: AI‑assistant‑as‑Makefile: a tool to create and manage AI agents using a simple YAML configuration.
+Author: Dmitriy Sorochenkov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dmtr/make-agent
+Project-URL: Repository, https://github.com/dmtr/make-agent
+Project-URL: Issues, https://github.com/dmtr/make-agent/issues
+Keywords: ai,agent,makefile,llm,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: any-llm-sdk[anthropic,ollama,openai,openrouter]==1.13.0
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# make-agent
+
+An AI agent whose system prompt and tools are defined in a Makefile.
+
+Each Makefile target annotated with a `# <tool>` comment block becomes a callable tool. The agent invokes targets via `make`, passing parameters as `KEY=value` arguments. A `define SYSTEM_PROMPT` block sets the agent's system prompt.
+
+## Installation
+
+```
+uv pip install .
+```
+
+Requires Python 3.11+ and a working `make` binary. Uses [any-llm-sdk](https://pypi.org/project/any-llm-sdk/) for model access, so any API keys (e.g. `ANTHROPIC_API_KEY`) must be set in the environment.
+
+## Usage
+
+```
+ANTHROPIC_API_KEY=<key> uv run make_agent [run] [-f FILE] [--model MODEL] [--prompt PROMPT | --prompt-file FILE] [--with-memory]
+```
+
+- `-f FILE` — Makefile to load. Searched in the current directory first, then `~/.make-agent/<project>/agents/`. Defaults to the value in `settings.yaml`, or `./Makefile` if not set.
+- `--model MODEL` — any-llm model string. Defaults to the value in `settings.yaml`.
+- `--prompt PROMPT` — send a single prompt and exit instead of entering the interactive shell
+- `--prompt-file FILE` — send a single prompt read from `FILE` and exit
+- `--agents-dir DIR` — directory for specialist `.mk` files (default: `~/.make-agent/<project>/agents/`)
+- `--agent-model MODEL` — model used when running specialist agents via `run_agent` (default: same as `--model`)
+- `--with-memory` — enable persistent conversation memory (see [Memory](#memory))
+- `--disable-builtin-tools TOOLS` — comma-separated built-in tool names to disable, or `all`
+- `--max-tool-output CHARS` — truncate tool stdout to this many characters; `0` = unlimited (default: 20000)
+- `--max-tokens N` — max tokens in the model response (default: 4096)
+- `--max-retries N` — max retry attempts on rate limit errors (default: 5)
+- `--tool-timeout SECONDS` — timeout for each tool subprocess (default: 600)
+- `--debug` — write all messages to `~/.make-agent/<project>/logs/make-agent.log`
+
+Without `--prompt`, the agent starts an interactive REPL. Type `exit`, `quit`, or press Ctrl-D to leave.
+
+### First run — setup wizard
+
+If no `settings.yaml` exists for the project and no Makefile is found automatically, the agent prompts you to create one:
+
+```
+No settings.yaml found for this project.
+Let's create one. Press Enter to accept the default shown in brackets.
+
+  Makefile path [Makefile]: ./my-agent.mk
+  Model [anthropic/claude-haiku-4-5-20251001]:
+
+Saved settings to ~/.make-agent/Users_alice_proj_myapp/settings.yaml
+```
+
+## Project settings
+
+All per-project data is stored under `~/.make-agent/`:
+
+```
+~/.make-agent/
+└── <project-slug>/          # e.g. Users_alice_proj_myapp
+    ├── settings.yaml        # default model and Makefile
+    ├── memory.db            # conversation history (when memory is enabled)
+    ├── agents/              # specialist agent .mk files
+    └── logs/
+        └── make-agent.log   # debug log (written when --debug is set)
+```
+
+The **project slug** is the absolute path of the working directory with the leading `/` stripped and remaining `/` replaced by `_`.
+
+### settings.yaml
+
+```yaml
+model: anthropic/claude-haiku-4-5-20251001
+makefile: ./my-agent.mk
+memory: true          # optional — enable persistent memory
+agent_model: anthropic/claude-opus-4-5  # optional — model for run_agent calls
+```
+
+All fields are optional. CLI flags always take precedence over `settings.yaml` values.
+
+## Makefile format
+
+```makefile
+define SYSTEM_PROMPT
+You are a filesystem assistant.
+endef
+
+.PHONY: list-files greet
+
+# <tool>
+# List files in a directory.
+# @param DIR string The directory path to list
+# </tool>
+list-files:
+	@ls -la $(DIR)
+
+# <tool>
+# Greet someone.
+# @param NAME string The name to greet
+# </tool>
+greet:
+	@echo "Hello, $(NAME)!"
+```
+
+### Special comment blocks
+
+- `define SYSTEM_PROMPT ... endef` sets the system prompt passed to the model. The content is raw text — no `#` prefix needed. `endef` must be on its own line with no indentation.
+- `# <tool> ... # </tool>` marks the following target as an LLM-callable tool. Lines starting with `# @param NAME type description` declare parameters (JSON Schema primitives: `string`, `number`, `integer`, `boolean`). All other lines form the tool description.
+
+### Parameters and `$(PARAM_FILE)`
+
+Every declared parameter automatically gets two Make variables injected at call time:
+
+- `$(PARAM)` — the value as a Make variable with shell-escaped value. Convenient for single-line values.
+- `$(PARAM_FILE)` — path to a temp file containing the full, unescaped value. Use this for multiline content or when the value might contain shell metacharacters.
+
+```makefile
+# <tool>
+# Write content to a file.
+# @param FILE_PATH string Destination file path
+# @param CONTENT string Content to write (may be multiline)
+# </tool>
+write-file:
+	@cat "$(CONTENT_FILE)" > "$(FILE_PATH)"
+```
+
+Targets without a `# <tool>` block are invisible to the model.
+
+## Built-in tools
+
+Every agent automatically receives four built-in tools alongside its Makefile-defined tools — no Makefile declaration needed:
+
+| Tool | What it does |
+|---|---|
+| `list_agent` | Scan the agents directory and return each specialist's name and description |
+| `validate_agent` | Parse and validate a named specialist's Makefile, reporting any errors |
+| `create_agent` | Generate a new `.mk` file from a YAML spec and save it to the agents directory |
+| `run_agent` | Delegate a task to a specialist agent and return its output |
+
+The agents directory defaults to `~/.make-agent/<project>/agents/` and can be changed with `--agents-dir`.
+
+## Memory
+
+Agents can persist every conversation turn to a local SQLite database and search it in future sessions.
+
+### Enabling memory
+
+```bash
+# One-time flag
+make_agent --with-memory -f my-agent.mk
+
+# Always on for this project (settings.yaml)
+memory: true
+```
+
+The database is stored at `~/.make-agent/<project-slug>/memory.db`. Every user message and final agent reply is written automatically.
+
+The project directory layout becomes:
+
+```
+~/.make-agent/
+└── <project-slug>/
+    ├── settings.yaml
+    ├── memory.db        # conversation history (created on first use)
+    ├── agents/
+    └── logs/
+```
+
+### Memory tools
+
+When memory is enabled, three additional built-in tools are injected:
+
+| Tool | What it does |
+|---|---|
+| `get_recent_messages(limit)` | Return the N most recent messages in chronological order |
+| `search_user_memory(query, limit, from_date, to_date)` | FTS5 keyword search over past user messages |
+| `search_agent_memory(query, limit, from_date, to_date)` | FTS5 keyword search over past agent replies |
+
+**FTS5 search tips** — the search is keyword-based, not semantic:
+
+- Use short keywords, not sentences: `"goal project"` not `"what is the goal of this project"`
+- Use `OR` for broader recall: `"goal OR objective OR purpose"`
+- Stop words (`the`, `of`, `is`, `a`) are not indexed — omit them
+- If a search returns nothing, retry with broader or alternative keywords
+- Use `get_recent_messages` when you need recent context and don't know which keywords to search for
+
+### Orchestrator pattern
+
+`examples/orchestra.mk` shows how to use the built-in tools to build a self-managing agent that creates and improves specialist agents at runtime:
+
+```bash
+# Interactive session
+make_agent -f examples/orchestra.mk
+
+# Single prompt
+make_agent -f examples/orchestra.mk --prompt "Summarise the git log for the last week"
+```
+
+For every task the orchestrator:
+
+1. Calls `list_agent` to discover available specialists.
+2. Delegates to an existing specialist with `run_agent`, or designs and saves a new one with `create_agent` first.
+3. Improves any specialist by calling `create_agent` with the same name — it overwrites the previous version.
+
+### YAML spec for `create_agent`
+
+```yaml
+system_prompt: "You are a specialist that searches source code for patterns."
+tools:
+  - name: search-files
+    description: Search files for a text pattern and return matching lines.
+    params:
+      - name: PATTERN
+        type: string
+        description: The text pattern to search for
+      - name: DIR
+        type: string
+        description: The directory to search in
+    recipe:
+      - '@grep -rn "$(PATTERN)" "$(DIR)" || echo "No matches found"'
+```
+
+`make-agent-create` converts this spec into a standard `make-agent` Makefile.
+
+## Example
+
+`examples/orchestra.mk` is the orchestrator agent — it manages specialist agents using the built-in tools and also exposes three simple no-parameter tools for system information:
+
+```bash
+make_agent -f examples/orchestra.mk
+```
+
+| Tool | Recipe |
+|---|---|
+| `current-dir` | `pwd` |
+| `os-info` | `uname -a` |
+| `current-date` | `date` |
+
+## Running tests
+
+```
+uv run pytest
+```

makefile_agent-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+make_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+make_agent/agent.py,sha256=lPPvCzWa_LrOGT38W-P2qjq7KmNyewtnUPfj18J4suA,7937
+make_agent/agent_shell.py,sha256=O29TibjzwN5vUhoVAnS2ZVv5V0hp6uoeRSFJGMWnXc4,2765
+make_agent/app_dirs.py,sha256=JCk0Q9nwgQ5hYpRYCvkcE0xkSq6ljMzsP7Z4fGtTJh4,1803
+make_agent/builtin_tools.py,sha256=jxJerZ1OIa-PjnkqcGG2GNjjQ-AVOymU5LmRKvoy1Ss,14978
+make_agent/create_agent.py,sha256=I0L2o1y-DoEo9F8Rk_4iTsuWrEZYVZJNHCvgqKeS4KQ,7343
+make_agent/main.py,sha256=7Nt1MhosTD-SQ8tSddEHIrPZFg6SVp2l4PnUCczn2WY,9175
+make_agent/memory.py,sha256=hiQJpt-O5SXETC-iKgTIWgsymT_2faGFTvoVHgtQoJA,5529
+make_agent/parser.py,sha256=YcbLacZfa6O3f88vYVpE9pOldPHVNiQ1KGC564YJxQs,13620
+make_agent/settings.py,sha256=r31KZDJLOB3U2Vpj0x3ZmbsZVOFrT58tiG9Bmw2LDVM,3264
+make_agent/tools.py,sha256=rUBpJ-3m1xRZtlzU9IGmUShBaDfCf7AJnNeXmQ_CTQM,7110
+make_agent/templates/orchestra.mk,sha256=6s-1TrQ8mbvXbJuQhg8grkGO0mCqqetvDoXHLXE8OwI,4232
+makefile_agent-0.3.0.dist-info/licenses/LICENSE,sha256=AMd6ov3p3D8YgzLdrgxkuVeYD96ngOr9QrUcR58gTJY,1076
+makefile_agent-0.3.0.dist-info/METADATA,sha256=OZAWDiqoVgxmK_vR9ImIQF42otC6qPodVMuiRNymp_U,9895
+makefile_agent-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+makefile_agent-0.3.0.dist-info/entry_points.txt,sha256=YTKP5Yp1oBx_GBi4jyr0B1BqxLPjL3e2jXmMezs2rtQ,101
+makefile_agent-0.3.0.dist-info/top_level.txt,sha256=TKwBMo6fYjF9KTNhHojXhp7jd0_w3pHxw34XVi7U0_g,11
+makefile_agent-0.3.0.dist-info/RECORD,,

makefile_agent-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

makefile_agent-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+make-agent-create = make_agent.create_agent:main
+make_agent = make_agent.main:main

makefile_agent-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitriy Sorochenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

makefile_agent-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+make_agent