makefile-agent 0.3.3__tar.gz → 0.4.0__tar.gz

makefile_agent-0.4.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: makefile-agent
+Version: 0.4.0
+Summary: An AI agent powered by Makefile skills.
+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: anthropic>=0.105.2
+Requires-Dist: openai>=1.0
+Requires-Dist: prompt-toolkit==3.0.52
+Dynamic: license-file
+
+# make-agent
+
+An AI agent powered by Makefile skills. Skills extend the agent with domain-specific instructions and shell tools.
+
+## Installation
+
+```
+pip install makefile-agent
+```
+
+Requires Python 3.11+ and a working `make` binary. Uses Anthropic and OpenAI SDKs for model access — set the appropriate provider API key in your environment (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`).
+
+## Usage
+
+```
+make_agent [run] --model MODEL [--prompt PROMPT | --prompt-file FILE]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--model MODEL` | — (required) | Model string (e.g. `claude-opus-4-5`, `gpt-4o`) |
+| `--skills-dir DIR` | `~/.make-agent/<project>/makefile/skills/` | Directory containing skills |
+| `--system PROMPT` | — | System prompt string (overrides SYSTEM.md discovery) |
+| `--system-file FILE` | — | Read system prompt from FILE (overrides SYSTEM.md discovery) |
+| `--prompt PROMPT` | — | Send a single prompt and exit (non-interactive) |
+| `--prompt-file FILE` | — | Read a single prompt from FILE and exit |
+| `--disable-builtin-tools TOOLS` | — | Comma-separated built-in tool names to disable, or `all` |
+| `--trusted-skills SKILLS` | — | Comma-separated trusted skills or `all`; trusted skills run without confirmation |
+| `--max-tool-output CHARS` | 32000 | Truncate tool output; `0` = unlimited |
+| `--max-tokens N` | 4096 | Max tokens in the model response |
+| `--reasoning-effort EFFORT` | `medium` | `none\|minimal\|low\|medium\|high\|xhigh` |
+| `--prompt-cache` | disabled | Enable Anthropic system-prompt caching |
+| `--compact-mode MODE` | `drop` | Context compaction strategy when context window is exceeded: `drop` removes oldest turns; `summarize` replaces turns with LLM-generated summaries |
+| `--max-retries N` | 5 | Max retries on rate-limit errors |
+| `--tool-timeout SECONDS` | 600 | Timeout per tool call |
+| `--loglevel LEVEL` | `INFO` | `DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL` |
+
+Without `--prompt`, the agent starts an interactive full-screen REPL. Press Ctrl-D, `/exit`, or `/quit` to leave.
+
+Interactive commands: `/help`, `/export` (save conversation to HTML), `/stats` (token usage totals), `/exit`, `/quit`.
+
+Useful keys: `Alt+Enter` inserts a newline, `Ctrl-C` cancels an in-flight turn, `Ctrl-T` focuses transcript view, then `Ctrl-P`/`Ctrl-N` moves between turns.
+
+## Project data
+
+All per-project data lives under `~/.make-agent/`:
+
+```
+~/.make-agent/
+└── <project-slug>/          # e.g. Users_alice_proj_myapp
+    ├── history              # shell input history
+    ├── makefile/
+    │   ├── SYSTEM.md        # default system prompt (copied from template on first run)
+    │   ├── skills/          # skill directories
+    │   └── memory.db        # conversation history
+    └── logs/
+        └── make-agent.log
+```
+
+The **project slug** is the absolute working-directory path with the leading `/` stripped and remaining `/` replaced by `_`.
+
+### System prompt discovery
+
+Priority order (first match wins):
+
+1. `--system PROMPT` flag
+2. `--system-file FILE` flag
+3. `SYSTEM.md` in the current working directory
+4. `~/.make-agent/<project>/makefile/SYSTEM.md` (created from a bundled template on first run)
+
+## Skills
+
+Each skill is a directory containing a single **`skill.mk`** file.
+
+```makefile
+define DESCRIPTION
+Searches files for a text pattern.
+endef
+
+.PHONY: search-files
+
+search-files:
+	@grep -rn "$$PATTERN" "$$DIR" || echo "No matches found"
+```
+
+The agent invokes targets via `make`, passing parameters as environment variables (`$$PARAM` in a recipe becomes `$PARAM` for the shell). The `define DESCRIPTION … endef` block is required and shown by `list_skills`.
+
+### Skill trust and approvals
+
+`execute_skill` requires confirmation when a skill is not trusted. In interactive mode, the shell prompts `[Y] approve / [N] deny`.
+
+Trust sources:
+
+- `--trusted-skills all` trusts all skills.
+- `--trusted-skills skill_name` trusts all targets in that skill.
+
+## Built-in tools
+
+| Tool | What it does |
+|---|---|
+| `list_skills` | List available skills with descriptions |
+| `read_skill` | Return the raw `skill.mk` content |
+| `execute_skill(name, command)` | Run a make command against a skill's `skill.mk` |
+| `create_skill` | Create or overwrite a skill (single `skill.mk` file) |
+| `validate_skill` | Validate that a `skill.mk` exists and has a `DESCRIPTION` block |
+| `write_file` | Write content to a file (sandboxed to the current working directory) |
+| `edit_file` | Replace a string in a file (sandboxed to the current working directory) |
+
+Use `--disable-builtin-tools` to turn off specific tools (or `all`).
+
+Safety constraints:
+
+- `write_file` and `edit_file` are sandboxed to paths inside the current working directory.
+- `execute_skill` blocks dangerous make options (`-f/--file`, `-C/--directory`, `-I/--include-dir`, `--eval`).
+
+## Memory
+
+Every conversation turn is persisted to a local SQLite database (`memory.db`), enabled by default.
+
+The database is created at `~/.make-agent/<project>/makefile/memory.db`.
+
+Three additional built-in tools are available:
+
+| Tool | What it does |
+|---|---|
+| `get_recent_messages(limit, from_date, to_date)` | Return 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: `"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
+- Fall back to `get_recent_messages` when you don't know which keywords to search for
+
+## Context compaction
+
+When the context window is exceeded the agent automatically compacts conversation history and retries. Two strategies are available via `--compact-mode`:
+
+- **`drop`** (default) — removes the oldest turns, keeping the most recent two.
+- **`summarize`** — replaces prior turns with LLM-generated summaries, preserving more context at the cost of an extra API call.
+
+Up to 3 compaction attempts are made before the request is aborted.
+
+## Development checks
+
+```
+uv run pytest
+uv run ruff check make_agent/
+uv run ruff format make_agent/
+```

makefile_agent-0.4.0/README.md

@@ -0,0 +1,152 @@
+# make-agent
+
+An AI agent powered by Makefile skills. Skills extend the agent with domain-specific instructions and shell tools.
+
+## Installation
+
+```
+pip install makefile-agent
+```
+
+Requires Python 3.11+ and a working `make` binary. Uses Anthropic and OpenAI SDKs for model access — set the appropriate provider API key in your environment (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`).
+
+## Usage
+
+```
+make_agent [run] --model MODEL [--prompt PROMPT | --prompt-file FILE]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--model MODEL` | — (required) | Model string (e.g. `claude-opus-4-5`, `gpt-4o`) |
+| `--skills-dir DIR` | `~/.make-agent/<project>/makefile/skills/` | Directory containing skills |
+| `--system PROMPT` | — | System prompt string (overrides SYSTEM.md discovery) |
+| `--system-file FILE` | — | Read system prompt from FILE (overrides SYSTEM.md discovery) |
+| `--prompt PROMPT` | — | Send a single prompt and exit (non-interactive) |
+| `--prompt-file FILE` | — | Read a single prompt from FILE and exit |
+| `--disable-builtin-tools TOOLS` | — | Comma-separated built-in tool names to disable, or `all` |
+| `--trusted-skills SKILLS` | — | Comma-separated trusted skills or `all`; trusted skills run without confirmation |
+| `--max-tool-output CHARS` | 32000 | Truncate tool output; `0` = unlimited |
+| `--max-tokens N` | 4096 | Max tokens in the model response |
+| `--reasoning-effort EFFORT` | `medium` | `none\|minimal\|low\|medium\|high\|xhigh` |
+| `--prompt-cache` | disabled | Enable Anthropic system-prompt caching |
+| `--compact-mode MODE` | `drop` | Context compaction strategy when context window is exceeded: `drop` removes oldest turns; `summarize` replaces turns with LLM-generated summaries |
+| `--max-retries N` | 5 | Max retries on rate-limit errors |
+| `--tool-timeout SECONDS` | 600 | Timeout per tool call |
+| `--loglevel LEVEL` | `INFO` | `DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL` |
+
+Without `--prompt`, the agent starts an interactive full-screen REPL. Press Ctrl-D, `/exit`, or `/quit` to leave.
+
+Interactive commands: `/help`, `/export` (save conversation to HTML), `/stats` (token usage totals), `/exit`, `/quit`.
+
+Useful keys: `Alt+Enter` inserts a newline, `Ctrl-C` cancels an in-flight turn, `Ctrl-T` focuses transcript view, then `Ctrl-P`/`Ctrl-N` moves between turns.
+
+## Project data
+
+All per-project data lives under `~/.make-agent/`:
+
+```
+~/.make-agent/
+└── <project-slug>/          # e.g. Users_alice_proj_myapp
+    ├── history              # shell input history
+    ├── makefile/
+    │   ├── SYSTEM.md        # default system prompt (copied from template on first run)
+    │   ├── skills/          # skill directories
+    │   └── memory.db        # conversation history
+    └── logs/
+        └── make-agent.log
+```
+
+The **project slug** is the absolute working-directory path with the leading `/` stripped and remaining `/` replaced by `_`.
+
+### System prompt discovery
+
+Priority order (first match wins):
+
+1. `--system PROMPT` flag
+2. `--system-file FILE` flag
+3. `SYSTEM.md` in the current working directory
+4. `~/.make-agent/<project>/makefile/SYSTEM.md` (created from a bundled template on first run)
+
+## Skills
+
+Each skill is a directory containing a single **`skill.mk`** file.
+
+```makefile
+define DESCRIPTION
+Searches files for a text pattern.
+endef
+
+.PHONY: search-files
+
+search-files:
+	@grep -rn "$$PATTERN" "$$DIR" || echo "No matches found"
+```
+
+The agent invokes targets via `make`, passing parameters as environment variables (`$$PARAM` in a recipe becomes `$PARAM` for the shell). The `define DESCRIPTION … endef` block is required and shown by `list_skills`.
+
+### Skill trust and approvals
+
+`execute_skill` requires confirmation when a skill is not trusted. In interactive mode, the shell prompts `[Y] approve / [N] deny`.
+
+Trust sources:
+
+- `--trusted-skills all` trusts all skills.
+- `--trusted-skills skill_name` trusts all targets in that skill.
+
+## Built-in tools
+
+| Tool | What it does |
+|---|---|
+| `list_skills` | List available skills with descriptions |
+| `read_skill` | Return the raw `skill.mk` content |
+| `execute_skill(name, command)` | Run a make command against a skill's `skill.mk` |
+| `create_skill` | Create or overwrite a skill (single `skill.mk` file) |
+| `validate_skill` | Validate that a `skill.mk` exists and has a `DESCRIPTION` block |
+| `write_file` | Write content to a file (sandboxed to the current working directory) |
+| `edit_file` | Replace a string in a file (sandboxed to the current working directory) |
+
+Use `--disable-builtin-tools` to turn off specific tools (or `all`).
+
+Safety constraints:
+
+- `write_file` and `edit_file` are sandboxed to paths inside the current working directory.
+- `execute_skill` blocks dangerous make options (`-f/--file`, `-C/--directory`, `-I/--include-dir`, `--eval`).
+
+## Memory
+
+Every conversation turn is persisted to a local SQLite database (`memory.db`), enabled by default.
+
+The database is created at `~/.make-agent/<project>/makefile/memory.db`.
+
+Three additional built-in tools are available:
+
+| Tool | What it does |
+|---|---|
+| `get_recent_messages(limit, from_date, to_date)` | Return 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: `"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
+- Fall back to `get_recent_messages` when you don't know which keywords to search for
+
+## Context compaction
+
+When the context window is exceeded the agent automatically compacts conversation history and retries. Two strategies are available via `--compact-mode`:
+
+- **`drop`** (default) — removes the oldest turns, keeping the most recent two.
+- **`summarize`** — replaces prior turns with LLM-generated summaries, preserving more context at the cost of an extra API call.
+
+Up to 3 compaction attempts are made before the request is aborted.
+
+## Development checks
+
+```
+uv run pytest
+uv run ruff check make_agent/
+uv run ruff format make_agent/
+```

makefile_agent-0.4.0/make_agent/agent_core/__init__.py

@@ -0,0 +1,104 @@
+from .agent import Agent, AgentManager, SessionNotFoundError
+from .bridge import (
+    ApprovalRequested,
+    ApproveSkill,
+    CancelTurn,
+    DenySkill,
+    HistoryCompacted,
+    ManagerError,
+    ShellCommand,
+    ShellEvent,
+    Shutdown,
+    StartTurn,
+    StatusChanged,
+    ToolFinished,
+    ToolStarted,
+    TokenEmitted,
+    TurnCancelled,
+    TurnFinished,
+    TurnStarted,
+)
+from .constants import (
+    DEFAULT_COMPACT_MODE,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_TOKENS,
+    DEFAULT_MAX_TOOL_OUTPUT,
+    DEFAULT_REASONING_EFFORT,
+    DEFAULT_TOOL_TIMEOUT,
+    DEFAULT_USE_PROMPT_CACHE,
+)
+from .events import (
+    AgentEvent,
+    CompactEvent,
+    ConfirmEvent,
+    DoneEvent,
+    TokenEvent,
+    ToolDoneEvent,
+    ToolStartEvent,
+    UsageEvent,
+)
+from .export import _render_html, export_conversation
+from .loop import (
+    AgentConfig,
+    AgenticLoop,
+    CallBack,
+    CompactCallback,
+    MessageCallback,
+    TokenCallback,
+    ToolCallback,
+    UsageCallback,
+)
+from .middleware import MiddlewareBase, Request, Response, SessionMiddleware
+
+__all__ = [
+    "DEFAULT_COMPACT_MODE",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_MAX_TOKENS",
+    "DEFAULT_MAX_TOOL_OUTPUT",
+    "DEFAULT_REASONING_EFFORT",
+    "DEFAULT_TOOL_TIMEOUT",
+    "DEFAULT_USE_PROMPT_CACHE",
+    "Agent",
+    "AgentConfig",
+    "AgentEvent",
+    "AgenticLoop",
+    "AgentManager",
+    "ApprovalRequested",
+    "ApproveSkill",
+    "CancelTurn",
+    "CompactEvent",
+    "ConfirmEvent",
+    "DenySkill",
+    "DoneEvent",
+    "HistoryCompacted",
+    "ManagerError",
+    "MiddlewareBase",
+    "Request",
+    "Response",
+    "SessionMiddleware",
+    "SessionNotFoundError",
+    "ShellCommand",
+    "ShellEvent",
+    "Shutdown",
+    "StartTurn",
+    "StatusChanged",
+    "ToolFinished",
+    "ToolStarted",
+    "TokenEmitted",
+    "TokenEvent",
+    "ToolDoneEvent",
+    "ToolStartEvent",
+    "TurnCancelled",
+    "TurnFinished",
+    "TurnStarted",
+    "_render_html",
+    "export_conversation",
+    # Internal — kept for AgenticLoop.arun() and tests only:
+    "CallBack",
+    "CompactCallback",
+    "MessageCallback",
+    "TokenCallback",
+    "ToolCallback",
+    "UsageCallback",
+    "UsageEvent",
+]