From d6f6c3d20bcacd7264743c2cfb7493d48d1e13e3 Mon Sep 17 00:00:00 2001 From: folathecoder Date: Tue, 7 Jul 2026 11:22:06 +0100 Subject: [PATCH 1/3] Add print_events, a live CLI renderer for the agent event stream --- src/agentling/events.py | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/agentling/events.py b/src/agentling/events.py index 301e659..881eeaa 100644 --- a/src/agentling/events.py +++ b/src/agentling/events.py @@ -10,6 +10,8 @@ from __future__ import annotations +import json +from collections.abc import AsyncIterator from dataclasses import dataclass from .memory import Step, ToolResult @@ -54,3 +56,46 @@ class FinalEvent: # Public union type for the values yielded by the agent's event stream. Event = TextDelta | ToolCallEvent | ToolResultEvent | StepEvent | FinalEvent + + +def _truncate(text: str, limit: int = 500) -> str: + """Shorten long tool output so a live stream stays readable.""" + + return text if len(text) <= limit else text[:limit] + "..." + + +async def print_events(events: AsyncIterator[Event]) -> str: + """Render an agent's event stream to stdout as it arrives. + + Consumes the iterator from Agent.run(..., stream=True): assistant text + prints token by token, each tool call and its result get their own line, + and the final answer is shown at the end. Returns that answer so the caller + can keep using it once the run has been displayed. + """ + + answer = "" + mid_line = False # True while streamed text has left the cursor mid-line. + + async for event in events: + match event: + case TextDelta(text=text): + print(text, end="", flush=True) + mid_line = True + case ToolCallEvent(tool_call=call): + if mid_line: + print() + mid_line = False + print(f"-> {call.name}({json.dumps(call.arguments)})") + case ToolResultEvent(result=result): + status = "error" if result.is_error else "ok" + print(f"<- [{status}] {_truncate(result.content)}") + case FinalEvent(answer=final): + if mid_line: + print() + mid_line = False + answer = final + print(f"= {final}") + case StepEvent(): + pass # Its contents already surfaced through the events above. + + return answer From fc83f01d31cc4d0c36830d3516f9bc90a57dee50 Mon Sep 17 00:00:00 2001 From: folathecoder Date: Tue, 7 Jul 2026 11:22:12 +0100 Subject: [PATCH 2/3] Add markdown skill loader with SKILL.md frontmatter A Skill is a folder holding a SKILL.md: YAML frontmatter (name, description, and optional tool entry points) followed by a markdown instruction body. Skill.from_path parses and validates it; load_tools resolves declared "module:attribute" entry points to Tool objects. Adds pyyaml and a code-reviewer example skill. --- examples/skills/code-reviewer/SKILL.md | 33 +++ pyproject.toml | 2 + src/agentling/skills.py | 109 ++++++++++ tests/test_skills.py | 281 +++++++++++++++++++++++++ uv.lock | 72 ++++++- 5 files changed, 496 insertions(+), 1 deletion(-) create mode 100644 examples/skills/code-reviewer/SKILL.md create mode 100644 src/agentling/skills.py create mode 100644 tests/test_skills.py diff --git a/examples/skills/code-reviewer/SKILL.md b/examples/skills/code-reviewer/SKILL.md new file mode 100644 index 0000000..753d70b --- /dev/null +++ b/examples/skills/code-reviewer/SKILL.md @@ -0,0 +1,33 @@ +--- +name: code-reviewer +description: Review a code change for bugs, security issues, and style problems. +--- + +# Code Reviewer + +You are reviewing a code change. Work through it methodically and report only +findings you are confident about. Prefer a few high-signal comments over a long +list of nits. + +## What to look for + +1. **Correctness** — off-by-one errors, wrong boundary conditions, unhandled + `None`/null, incorrect error handling, and logic that does not match the + stated intent. +2. **Security** — unsanitized input reaching a query, command, or file path; + secrets committed to source; unsafe deserialization; missing authorization + checks. +3. **Resource handling** — files, sockets, and locks that are opened but not + reliably closed; unbounded growth; work done inside a loop that belongs + outside it. +4. **Readability** — unclear names, dead code, and comments that no longer + match the code. + +## How to report + +For each finding, give the location, a one-line description of the problem, and +a concrete fix. Use this shape: + +- `path/to/file.py:42` — → + +If the change looks correct, say so plainly rather than inventing problems. diff --git a/pyproject.toml b/pyproject.toml index fb4b43d..ed2f95d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,7 @@ classifiers = [ ] dependencies = [ "openai>=2.44.0", + "pyyaml>=6.0", ] [project.urls] @@ -38,4 +39,5 @@ testpaths = ["tests"] dev = [ "pytest>=9.1.1", "pytest-asyncio>=1.4.0", + "types-PyYAML>=6.0", ] diff --git a/src/agentling/skills.py b/src/agentling/skills.py new file mode 100644 index 0000000..e53d75d --- /dev/null +++ b/src/agentling/skills.py @@ -0,0 +1,109 @@ +"""Markdown skills with progressive disclosure. + +A skill is a folder containing a SKILL.md file: YAML frontmatter (name, +description, and optional tool entry points) followed by a markdown body of +instructions. Only the name and description are shown to the model up front, in +a catalog appended to the system prompt. The full body, and any tools the skill +declares, are revealed on demand when the model calls the built-in load_skill +tool. That keeps the base context small until a skill is actually needed. +""" + +from __future__ import annotations + +import importlib +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +import yaml + +from .tools import Tool + +SKILL_FILE = "SKILL.md" + + +@dataclass +class Skill: + """A loadable unit of instructions plus optional tools. + + name and description are cheap metadata for the catalog. instructions is the + full markdown body, revealed only when the skill is loaded. tools lists + Python entry points ("package.module:attribute") that resolve to Tool + objects and are registered at load time. path is the skill's folder, so the + instructions can reference files bundled alongside SKILL.md. + """ + + name: str + description: str + instructions: str + path: Path + tools: list[str] = field(default_factory=list) + + @classmethod + def from_path(cls, path: str | Path) -> Skill: + """Load a Skill from a folder containing a SKILL.md file.""" + + folder = Path(path) + source = (folder / SKILL_FILE).read_text(encoding="utf-8") + frontmatter, body = _split_frontmatter(source) + + try: + name = frontmatter["name"] + description = frontmatter["description"] + except KeyError as exc: + raise ValueError( + f"{folder / SKILL_FILE} is missing required frontmatter key {exc}." + ) from exc + + return cls( + name=name, + description=description, + instructions=body.strip(), + path=folder, + tools=list(frontmatter.get("tools") or []), + ) + + def load_tools(self) -> list[Tool]: + """Import and return the Tool objects named in this skill's frontmatter.""" + + return [_resolve_tool(spec) for spec in self.tools] + + +def _split_frontmatter(source: str) -> tuple[dict[str, Any], str]: + """Split a SKILL.md into its YAML frontmatter dict and markdown body. + + The frontmatter is the block between the leading '---' fence and the next + '---' line. A file with no leading fence is treated as all body. + """ + + if not source.startswith("---"): + return {}, source + + # maxsplit=2 splits on only the first two fences, so a '---' horizontal + # rule inside the body is left intact. parts[0] is empty because the + # string starts with the opening fence. + parts = source.split("---", 2) + if len(parts) < 3: + raise ValueError("Unterminated SKILL.md frontmatter (missing closing '---').") + + data = yaml.safe_load(parts[1]) or {} + if not isinstance(data, dict): + raise ValueError("SKILL.md frontmatter must be a YAML mapping.") + + return data, parts[2] + + +def _resolve_tool(spec: str) -> Tool: + """Resolve a 'package.module:attribute' entry point to a Tool instance.""" + + module_path, sep, attr = spec.partition(":") + if not sep: + raise ValueError(f"Tool entry point {spec!r} must be 'module.path:attribute'.") + + obj = getattr(importlib.import_module(module_path), attr) + if not isinstance(obj, Tool): + raise TypeError( + f"Tool entry point {spec!r} resolved to {type(obj).__name__}, " + "expected a Tool (did you forget the @tool decorator?)." + ) + return obj diff --git a/tests/test_skills.py b/tests/test_skills.py new file mode 100644 index 0000000..d485e30 --- /dev/null +++ b/tests/test_skills.py @@ -0,0 +1,281 @@ +from pathlib import Path + +import pytest + +from agentling.skills import Skill, _resolve_tool, _split_frontmatter +from agentling.tools import tool + + +@tool +def sample_tool(x: int) -> int: + """Double a number. + + Args: + x: The number to double. + """ + return x * 2 + + +# A non-Tool module attribute, used to exercise the entry-point type guard. +not_a_tool = 123 + + +def _write_skill(folder: Path, text: str) -> Path: + """Create a skill folder containing a SKILL.md with the given contents.""" + + folder.mkdir(parents=True, exist_ok=True) + (folder / "SKILL.md").write_text(text, encoding="utf-8") + return folder + + +# --------------------------------------------------------------------------- # +# Skill.from_path — happy path +# --------------------------------------------------------------------------- # +def test_from_path_reads_name_description_and_body(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "greeter", + "---\n" + "name: greeter\n" + "description: Greet the user warmly.\n" + "---\n" + "# Greeter\n" + "\n" + "Say hello.\n", + ) + + skill = Skill.from_path(folder) + + assert skill.name == "greeter" + assert skill.description == "Greet the user warmly." + assert skill.instructions == "# Greeter\n\nSay hello." + assert skill.path == folder + assert skill.tools == [] + + +def test_from_path_accepts_a_string_path(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "s", + "---\nname: s\ndescription: d\n---\nbody\n", + ) + + skill = Skill.from_path(str(folder)) + + assert skill.name == "s" + assert skill.path == folder + + +def test_from_path_parses_a_tools_list(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "reviewer", + "---\n" + "name: reviewer\n" + "description: Review code.\n" + "tools:\n" + " - some.module:thing\n" + " - other.module:other\n" + "---\n" + "body\n", + ) + + skill = Skill.from_path(folder) + + assert skill.tools == ["some.module:thing", "other.module:other"] + + +def test_from_path_empty_tools_key_yields_no_tools(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "s", + "---\nname: s\ndescription: d\ntools:\n---\nbody\n", + ) + + skill = Skill.from_path(folder) + + # `tools:` with no value parses to None, which must normalize to []. + assert skill.tools == [] + + +def test_from_path_preserves_horizontal_rule_in_body(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "s", + "---\n" + "name: s\n" + "description: d\n" + "---\n" + "Section one\n" + "\n" + "---\n" + "\n" + "Section two\n", + ) + + skill = Skill.from_path(folder) + + # The '---' rule inside the body must survive: only the first two fences + # delimit the frontmatter. + assert "---" in skill.instructions + assert "Section one" in skill.instructions + assert "Section two" in skill.instructions + + +# --------------------------------------------------------------------------- # +# Skill.from_path — error paths +# --------------------------------------------------------------------------- # +def test_from_path_missing_name_raises(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "s", + "---\ndescription: d\n---\nbody\n", + ) + + with pytest.raises(ValueError, match="missing required frontmatter key 'name'"): + Skill.from_path(folder) + + +def test_from_path_missing_description_raises(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "s", + "---\nname: s\n---\nbody\n", + ) + + with pytest.raises( + ValueError, match="missing required frontmatter key 'description'" + ): + Skill.from_path(folder) + + +def test_from_path_error_names_the_file(tmp_path: Path) -> None: + folder = _write_skill(tmp_path / "s", "---\ndescription: d\n---\nbody\n") + + with pytest.raises(ValueError, match="SKILL.md"): + Skill.from_path(folder) + + +def test_from_path_missing_file_raises(tmp_path: Path) -> None: + with pytest.raises(FileNotFoundError): + Skill.from_path(tmp_path / "does_not_exist") + + +# --------------------------------------------------------------------------- # +# _split_frontmatter +# --------------------------------------------------------------------------- # +def test_split_no_leading_fence_is_all_body() -> None: + data, body = _split_frontmatter("# Just markdown\n") + + assert data == {} + assert body == "# Just markdown\n" + + +def test_split_returns_mapping_and_body() -> None: + data, body = _split_frontmatter("---\nname: x\ndescription: y\n---\nHello") + + assert data == {"name": "x", "description": "y"} + assert body == "\nHello" + + +def test_split_empty_frontmatter_returns_empty_dict() -> None: + data, body = _split_frontmatter("---\n---\nbody") + + assert data == {} + assert "body" in body + + +def test_split_unterminated_frontmatter_raises() -> None: + with pytest.raises(ValueError, match="Unterminated"): + _split_frontmatter("---\nname: x\n") + + +def test_split_non_mapping_frontmatter_raises() -> None: + with pytest.raises(ValueError, match="YAML mapping"): + _split_frontmatter("---\njust a scalar\n---\nbody") + + +# --------------------------------------------------------------------------- # +# _resolve_tool +# --------------------------------------------------------------------------- # +def test_resolve_tool_returns_the_tool_instance() -> None: + resolved = _resolve_tool(f"{__name__}:sample_tool") + + assert resolved is sample_tool + assert resolved.name == "sample_tool" + + +def test_resolve_tool_missing_colon_raises() -> None: + with pytest.raises(ValueError, match="must be"): + _resolve_tool("no_colon_here") + + +def test_resolve_tool_non_tool_target_raises() -> None: + with pytest.raises(TypeError, match="expected a Tool"): + _resolve_tool(f"{__name__}:not_a_tool") + + +def test_resolve_tool_unknown_module_raises() -> None: + with pytest.raises(ModuleNotFoundError): + _resolve_tool("agentling._definitely_not_a_module:thing") + + +def test_resolve_tool_unknown_attribute_raises() -> None: + with pytest.raises(AttributeError): + _resolve_tool(f"{__name__}:missing_attribute") + + +# --------------------------------------------------------------------------- # +# Skill.load_tools +# --------------------------------------------------------------------------- # +def test_load_tools_empty_returns_empty_list() -> None: + skill = Skill( + name="x", description="y", instructions="", path=Path("."), tools=[] + ) + + assert skill.load_tools() == [] + + +def test_load_tools_resolves_declared_entry_points() -> None: + skill = Skill( + name="x", + description="y", + instructions="", + path=Path("."), + tools=[f"{__name__}:sample_tool"], + ) + + tools = skill.load_tools() + + assert tools == [sample_tool] + assert tools[0].name == "sample_tool" + + +def test_from_path_then_load_tools_end_to_end(tmp_path: Path) -> None: + folder = _write_skill( + tmp_path / "review", + "---\n" + "name: review\n" + "description: Review code.\n" + "tools:\n" + f" - {__name__}:sample_tool\n" + "---\n" + "Review carefully.\n", + ) + + skill = Skill.from_path(folder) + loaded = skill.load_tools() + + assert skill.instructions == "Review carefully." + assert [t.name for t in loaded] == ["sample_tool"] + + +# --------------------------------------------------------------------------- # +# Bundled example +# --------------------------------------------------------------------------- # +def test_bundled_code_reviewer_example_loads() -> None: + example = ( + Path(__file__).parent.parent + / "examples" + / "skills" + / "code-reviewer" + ) + + skill = Skill.from_path(example) + + assert skill.name == "code-reviewer" + assert skill.description + assert skill.instructions.startswith("# Code Reviewer") diff --git a/uv.lock b/uv.lock index e52005d..74a1ad3 100644 --- a/uv.lock +++ b/uv.lock @@ -8,21 +8,27 @@ version = "0.0.1" source = { editable = "." } dependencies = [ { name = "openai" }, + { name = "pyyaml" }, ] [package.dev-dependencies] dev = [ { name = "pytest" }, { name = "pytest-asyncio" }, + { name = "types-pyyaml" }, ] [package.metadata] -requires-dist = [{ name = "openai", specifier = ">=2.44.0" }] +requires-dist = [ + { name = "openai", specifier = ">=2.44.0" }, + { name = "pyyaml", specifier = ">=6.0" }, +] [package.metadata.requires-dev] dev = [ { name = "pytest", specifier = ">=9.1.1" }, { name = "pytest-asyncio", specifier = ">=1.4.0" }, + { name = "types-pyyaml", specifier = ">=6.0" }, ] [[package]] @@ -407,6 +413,61 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/03/e2/08a497ef684b88559c9cc5f4ad53a37e7b99e727094a86d6ea32536d5d3c/pytest_asyncio-1.4.0-py3-none-any.whl", hash = "sha256:933ca923a23075a87fb7070c0ec272a6848489824d887c85c812670932835aa1", size = 16930, upload-time = "2026-05-26T09:56:02.576Z" }, ] +[[package]] +name = "pyyaml" +version = "6.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6d/16/a95b6757765b7b031c9374925bb718d55e0a9ba8a1b6a12d25962ea44347/pyyaml-6.0.3-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", size = 185826, upload-time = "2025-09-25T21:31:58.655Z" }, + { url = "https://files.pythonhosted.org/packages/16/19/13de8e4377ed53079ee996e1ab0a9c33ec2faf808a4647b7b4c0d46dd239/pyyaml-6.0.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", size = 175577, upload-time = "2025-09-25T21:32:00.088Z" }, + { url = "https://files.pythonhosted.org/packages/0c/62/d2eb46264d4b157dae1275b573017abec435397aa59cbcdab6fc978a8af4/pyyaml-6.0.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", size = 775556, upload-time = "2025-09-25T21:32:01.31Z" }, + { url = "https://files.pythonhosted.org/packages/10/cb/16c3f2cf3266edd25aaa00d6c4350381c8b012ed6f5276675b9eba8d9ff4/pyyaml-6.0.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", size = 882114, upload-time = "2025-09-25T21:32:03.376Z" }, + { url = "https://files.pythonhosted.org/packages/71/60/917329f640924b18ff085ab889a11c763e0b573da888e8404ff486657602/pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", size = 806638, upload-time = "2025-09-25T21:32:04.553Z" }, + { url = "https://files.pythonhosted.org/packages/dd/6f/529b0f316a9fd167281a6c3826b5583e6192dba792dd55e3203d3f8e655a/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", size = 767463, upload-time = "2025-09-25T21:32:06.152Z" }, + { url = "https://files.pythonhosted.org/packages/f2/6a/b627b4e0c1dd03718543519ffb2f1deea4a1e6d42fbab8021936a4d22589/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", size = 794986, upload-time = "2025-09-25T21:32:07.367Z" }, + { url = "https://files.pythonhosted.org/packages/45/91/47a6e1c42d9ee337c4839208f30d9f09caa9f720ec7582917b264defc875/pyyaml-6.0.3-cp311-cp311-win32.whl", hash = "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", size = 142543, upload-time = "2025-09-25T21:32:08.95Z" }, + { url = "https://files.pythonhosted.org/packages/da/e3/ea007450a105ae919a72393cb06f122f288ef60bba2dc64b26e2646fa315/pyyaml-6.0.3-cp311-cp311-win_amd64.whl", hash = "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", size = 158763, upload-time = "2025-09-25T21:32:09.96Z" }, + { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" }, + { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" }, + { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" }, + { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" }, + { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" }, + { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" }, + { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" }, + { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" }, + { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" }, + { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" }, + { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" }, + { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" }, + { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" }, + { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" }, + { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" }, + { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" }, + { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" }, + { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, + { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" }, + { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" }, + { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" }, + { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" }, + { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" }, + { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" }, + { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" }, + { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" }, + { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" }, + { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" }, + { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" }, + { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" }, + { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" }, + { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" }, + { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" }, + { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" }, + { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" }, +] + [[package]] name = "sniffio" version = "1.3.1" @@ -428,6 +489,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d8/8e/bb97bb0c71802080bfc8952937d174e49cfc50de5c951dd47b2496f0dcdb/tqdm-4.68.3-py3-none-any.whl", hash = "sha256:39832cc2def2789a6f29df83f172db7416cea70052c0907a57801c5f2fdccb03", size = 78337, upload-time = "2026-06-17T07:36:50.132Z" }, ] +[[package]] +name = "types-pyyaml" +version = "6.0.12.20260518" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b8/83/4a1afc3fbfcf5b8d46fc390cd95ed6b0dc9010a265f4e9f46314efffa37a/types_pyyaml-6.0.12.20260518.tar.gz", hash = "sha256:d917f83fb38462550338c1297faedd860b3ec83912b96b1e3d73255f7473e466", size = 17850, upload-time = "2026-05-18T06:01:58.675Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/06/a2/c01db32be2ae7d6a1689972f3c492b149ee4e164b12fdfd9f64b50888215/types_pyyaml-6.0.12.20260518-py3-none-any.whl", hash = "sha256:d2150f75a231c9fe9c7463bd29487d93e60bac90400287351384bc2284eba7cd", size = 20312, upload-time = "2026-05-18T06:01:57.368Z" }, +] + [[package]] name = "typing-extensions" version = "4.16.0" From 129a17ca3ee9d1d719ef6dfbc4b10fa6e2f4a1e2 Mon Sep 17 00:00:00 2001 From: folathecoder Date: Tue, 7 Jul 2026 11:22:19 +0100 Subject: [PATCH 3/3] Stream the agent loop end to end and wire in skills Drive each model turn through model.stream and agglomerate_deltas, emitting TextDelta as tokens arrive. Register skills with progressive disclosure: only names and descriptions go in the system prompt, and the built-in load_skill tool reveals a skill's body and registers its tools on demand. Also fold in three review fixes: - Guard max_steps < 1 instead of silently falling back to the default. - Reject duplicate tool names at construction. - Add run() overloads: stream=False types as Awaitable[str], stream=True as AsyncIterator[Event]. --- src/agentling/agent.py | 177 +++++++++++++++++++++++++++++++++---- tests/test_agent.py | 195 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 350 insertions(+), 22 deletions(-) diff --git a/src/agentling/agent.py b/src/agentling/agent.py index dd1eb72..9bd17c2 100644 --- a/src/agentling/agent.py +++ b/src/agentling/agent.py @@ -4,21 +4,34 @@ typed steps) into an async ReAct loop. One async generator, _run_stream, does the real work and yields Events. run() is a thin dispatcher: it hands back that stream when stream is True, or drains it and returns the final answer otherwise. + +Skills are disclosed progressively: only their names and descriptions are added +to the system prompt up front. The full instructions, and any tools a skill +declares, arrive when the model calls the built-in load_skill tool. """ from __future__ import annotations import asyncio -import time import json +import time +from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Sequence from dataclasses import replace -from collections.abc import AsyncIterator, Callable, Sequence -from typing import Any - -from .events import Event, FinalEvent, StepEvent, ToolCallEvent, ToolResultEvent +from pathlib import Path +from typing import Literal, overload + +from .events import ( + Event, + FinalEvent, + StepEvent, + TextDelta, + ToolCallEvent, + ToolResultEvent, +) from .memory import ActionStep, FinalStep, Memory, Step, TaskStep, ToolResult -from .models import ChatMessage, Model, ToolCall -from .tools import FinalAnswerTool, Tool +from .models import ChatMessage, Delta, Model, ToolCall, ToolSpec, agglomerate_deltas +from .skills import Skill +from .tools import FinalAnswerTool, Tool, ToolCallError, tool DEFAULT_INSTRUCTIONS = ( "You are a helpful agent. Use the available tools to gather information or " @@ -43,25 +56,75 @@ def __init__( self, model: Model, tools: Sequence[Tool] = (), - skills: Sequence[Any] = (), + skills: Sequence[Skill | str | Path] = (), instructions: str | None = None, max_steps: int = 15, step_callbacks: Sequence[Callable[[Step], None]] = (), parallel_tools: bool = True, ) -> None: + if max_steps < 1: + raise ValueError("max_steps must be at least 1.") + self.model = model - self.instructions = instructions or DEFAULT_INSTRUCTIONS self.max_steps = max_steps self.step_callbacks = list(step_callbacks) self.parallel_tools = parallel_tools - self.skills = list(skills) # accepted but not consumed yet self.memory = Memory() self._interrupt = asyncio.Event() - all_tools = [*tools, FinalAnswerTool()] - self.tools: dict[str, Tool] = {tool.name: tool for tool in all_tools} - self._tool_schemas = [tool.to_schema() for tool in all_tools] + # Register the caller's tools plus the always-available final_answer. A + # duplicate name among these is a programming error, so fail loudly here + # rather than silently letting one tool shadow another. + self.tools: dict[str, Tool] = {} + self._tool_schemas: list[ToolSpec] = [] + for base_tool in (*tools, FinalAnswerTool()): + if base_tool.name in self.tools: + raise ValueError(f"Duplicate tool name: {base_tool.name!r}") + self._register_tool(base_tool) + + # Load skills up front but reveal only their names and descriptions. The + # full instructions and any skill tools arrive when the model calls + # load_skill, which keeps the base context small (progressive disclosure). + self.skills: dict[str, Skill] = { + skill.name: skill for skill in (_as_skill(entry) for entry in skills) + } + self.instructions = instructions or DEFAULT_INSTRUCTIONS + if self.skills: + self._register_tool(self._build_load_skill_tool()) + self.instructions += _skill_catalog(self.skills.values()) + + def _register_tool(self, new_tool: Tool) -> None: + """Add a tool to the live tool set, skipping names already registered. + + Registration is idempotent so a skill can be loaded more than once, or + declare a tool the agent already has, without raising mid-run. + """ + + if new_tool.name in self.tools: + return + self.tools[new_tool.name] = new_tool + self._tool_schemas.append(new_tool.to_schema()) + + @overload + def run( + self, + task: str, + *, + stream: Literal[False] = False, + reset: bool = True, + max_steps: int | None = None, + ) -> Awaitable[str]: ... + + @overload + def run( + self, + task: str, + *, + stream: Literal[True], + reset: bool = True, + max_steps: int | None = None, + ) -> AsyncIterator[Event]: ... def run( self, @@ -70,10 +133,10 @@ def run( stream: bool = False, reset: bool = True, max_steps: int | None = None, - ) -> Any: + ) -> Awaitable[str] | AsyncIterator[Event]: """Run the agent on a task. - With stream=False (the default) this returns a coroutine that resolves + With stream=False (the default) this returns an awaitable that resolves to the final answer string: answer = await agent.run(task) @@ -83,6 +146,7 @@ def run( async for event in agent.run(task, stream=True): ... """ + events = self._run_stream(task, reset=reset, max_steps=max_steps) if stream: return events @@ -90,6 +154,7 @@ def run( async def _drain(self, events: AsyncIterator[Event]) -> str: """Consume the event stream and return the final answer.""" + answer = "" async for event in events: if isinstance(event, FinalEvent): @@ -100,12 +165,16 @@ async def _run_stream( self, task: str, *, reset: bool = True, max_steps: int | None = None ) -> AsyncIterator[Event]: """The core loop: drive the model/tool cycle, yielding Events.""" + if reset: self.memory.reset() + if max_steps is not None and max_steps < 1: + raise ValueError("max_steps must be at least 1.") + self.memory.add(TaskStep(task=task)) - limit = max_steps or self.max_steps + limit = self.max_steps if max_steps is None else max_steps # Remember the previous step's calls so we can spot an exact repeat. previous_signature: tuple[tuple[str, str], ...] | None = None @@ -118,7 +187,16 @@ async def _run_stream( started = time.monotonic() messages = self.memory.to_messages(self.instructions) - response = await self.model.generate(messages, tools=self._tool_schemas) + + # Stream the model turn: emit text as it arrives, then rebuild the + # full ChatMessage from the deltas for the rest of the step to use. + deltas: list[Delta] = [] + async for delta in self.model.stream(messages, tools=self._tool_schemas): + if delta.content: + yield TextDelta(text=delta.content) + deltas.append(delta) + + response = agglomerate_deltas(deltas) # Forgiving termination: no tool calls means the content is the answer. if not response.tool_calls: @@ -181,12 +259,22 @@ async def _run_stream( content="Step limit reached. Give your best final answer now.", ) ) - response = await self.model.generate(messages) + + deltas = [] + + async for delta in self.model.stream(messages): + if delta.content: + yield TextDelta(text=delta.content) + deltas.append(delta) + + response = agglomerate_deltas(deltas) self.memory.add(FinalStep(answer=response.content)) + yield FinalEvent(answer=response.content, usage=response.usage) async def _execute_tool(self, tool_call: ToolCall) -> ToolResult: """Run one tool call, turning any failure into an error observation.""" + tool = self.tools.get(tool_call.name) if tool is None: return ToolResult( @@ -216,10 +304,63 @@ async def _execute_tool(self, tool_call: ToolCall) -> ToolResult: is_error=False, ) + def _build_load_skill_tool(self) -> Tool: + """Build the built-in load_skill tool, bound to this agent's skills.""" + + @tool + def load_skill(name: str) -> str: + """Load a skill's full instructions and enable any tools it provides. + + Args: + name: The name of the skill to load, taken from the catalog in + the system prompt. + """ + + skill = self.skills.get(name) + if skill is None: + raise ToolCallError( + f"Unknown skill {name!r}. Available: {sorted(self.skills)}" + ) + + loaded = skill.load_tools() + for skill_tool in loaded: + self._register_tool(skill_tool) + + body = skill.instructions + if loaded: + names = ", ".join(skill_tool.name for skill_tool in loaded) + body += f"\n\nTools now available: {names}." + return body + + return load_skill + def interrupt(self) -> None: """Request a graceful stop before the next step. The current run pauses rather than crashing; resume it later with run(..., reset=False), which continues from the steps already in memory. """ + self._interrupt.set() + + +def _as_skill(entry: Skill | str | Path) -> Skill: + """Coerce a skill entry (a Skill, or a path to a skill folder) into a Skill.""" + + return entry if isinstance(entry, Skill) else Skill.from_path(entry) + + +def _skill_catalog(skills: Iterable[Skill]) -> str: + """Render the skill catalog appended to the system prompt. + + Only names and descriptions are listed. The full instructions stay out of + the prompt until the model loads a skill (progressive disclosure). + """ + + lines = "\n".join(f"- {skill.name}: {skill.description}" for skill in skills) + return ( + "\n\nYou can load skills: focused instruction sets for particular kinds " + "of task. When the task matches one, call load_skill(name) to load its " + "full instructions and any tools it provides before continuing. " + "Available skills:\n" + lines + ) diff --git a/tests/test_agent.py b/tests/test_agent.py index 8d99496..e8211a2 100644 --- a/tests/test_agent.py +++ b/tests/test_agent.py @@ -1,10 +1,21 @@ +import json from collections.abc import AsyncIterator, Sequence +from pathlib import Path from typing import Any +import pytest + from agentling.agent import Agent -from agentling.events import FinalEvent, StepEvent, ToolCallEvent, ToolResultEvent +from agentling.events import ( + FinalEvent, + StepEvent, + TextDelta, + ToolCallEvent, + ToolResultEvent, +) from agentling.memory import ActionStep, FinalStep, TaskStep -from agentling.models import ChatMessage, Delta, ToolCall, Usage +from agentling.models import ChatMessage, Delta, ToolCall, ToolCallDelta, Usage +from agentling.skills import Skill from agentling.tools import tool @@ -27,10 +38,28 @@ async def generate( self._index += 1 return response - def stream( + async def stream( self, messages: Sequence[ChatMessage], tools: Sequence[Any] | None = None ) -> AsyncIterator[Delta]: - raise NotImplementedError + # Replay the next scripted response as a delta stream that + # agglomerate_deltas rebuilds into the same ChatMessage. + self.calls.append(list(messages)) + response = self._responses[self._index] + self._index += 1 + if response.content: + yield Delta(content=response.content) + for index, tc in enumerate(response.tool_calls): + yield Delta( + tool_calls=[ + ToolCallDelta( + index=index, + id=tc.id, + name=tc.name, + arguments=json.dumps(tc.arguments), + ) + ] + ) + yield Delta(usage=response.usage) def _assistant( @@ -55,6 +84,34 @@ def add(a: int, b: int) -> int: return a + b +@tool +def multiply(a: int, b: int) -> int: + """Multiply two integers. + + Args: + a: The first number. + b: The second number. + """ + return a * b + + +_REVIEWER_SKILL = Skill( + name="reviewer", + description="Review code for bugs and style issues.", + instructions="Look for off-by-one errors and missing null checks.", + path=Path("."), + tools=[], +) + +_CALC_SKILL = Skill( + name="calc", + description="Do arithmetic with the multiply tool.", + instructions="Use the multiply tool to compute products.", + path=Path("."), + tools=[f"{__name__}:multiply"], +) + + # --------------------------------------------------------------------------- # # Termination paths # --------------------------------------------------------------------------- # @@ -172,6 +229,18 @@ async def test_streaming_yields_events() -> None: assert events[-1].answer == "2" +async def test_streaming_emits_text_deltas() -> None: + model = FakeModel([_assistant(content="hello world")]) + agent = Agent(model=model) + + texts = [ + event.text + async for event in agent.run("hi", stream=True) + if isinstance(event, TextDelta) + ] + assert "".join(texts) == "hello world" + + # --------------------------------------------------------------------------- # # max_steps forced answer # --------------------------------------------------------------------------- # @@ -321,3 +390,121 @@ def interrupt_once(step: object) -> None: assert await agent.run("continue", reset=False) == "finished on resume" assert len(model.calls) == 2 assert sum(isinstance(s, TaskStep) for s in agent.memory.steps) == 2 + + +# --------------------------------------------------------------------------- # +# Skills: progressive disclosure +# --------------------------------------------------------------------------- # +def _load_skill_turn(call_id: str, skill_name: str) -> ChatMessage: + """A model turn calling load_skill (whose own argument is named 'name').""" + return _assistant( + tool_calls=[ + ToolCall(id=call_id, name="load_skill", arguments={"name": skill_name}) + ] + ) + + +def test_skill_catalog_is_added_to_the_system_prompt() -> None: + agent = Agent(model=FakeModel([]), skills=[_REVIEWER_SKILL]) + + assert "load_skill" in agent.tools + assert "reviewer" in agent.instructions + assert "Review code for bugs and style issues." in agent.instructions + # Only the name and description surface up front; the body stays hidden + # until the skill is loaded. + assert "off-by-one" not in agent.instructions + + +def test_no_skills_means_no_load_skill_tool() -> None: + agent = Agent(model=FakeModel([])) + + assert "load_skill" not in agent.tools + + +async def test_load_skill_reveals_the_body() -> None: + model = FakeModel( + [ + _load_skill_turn("c1", "reviewer"), + _assistant(content="done"), + ] + ) + agent = Agent(model=model, skills=[_REVIEWER_SKILL]) + + assert await agent.run("review this") == "done" + action = agent.memory.steps[1] + assert isinstance(action, ActionStep) + assert action.tool_results[0].content == _REVIEWER_SKILL.instructions + assert action.tool_results[0].is_error is False + + +async def test_load_skill_registers_the_skills_tools() -> None: + model = FakeModel( + [ + _load_skill_turn("c1", "calc"), + _tool_turn("c2", "multiply", a=6, b=7), + _assistant(content="42"), + ] + ) + agent = Agent(model=model, skills=[_CALC_SKILL]) + + # multiply is hidden until the skill that provides it is loaded. + assert "multiply" not in agent.tools + + assert await agent.run("compute six times seven") == "42" + + assert "multiply" in agent.tools + load = agent.memory.steps[1] + assert isinstance(load, ActionStep) + assert "Tools now available: multiply." in load.tool_results[0].content + product = agent.memory.steps[2] + assert isinstance(product, ActionStep) + assert product.tool_results[0].content == "42" + + +async def test_load_unknown_skill_is_an_error_observation() -> None: + model = FakeModel( + [ + _load_skill_turn("c1", "ghost"), + _assistant(content="recovered"), + ] + ) + agent = Agent(model=model, skills=[_REVIEWER_SKILL]) + + assert await agent.run("load a missing skill") == "recovered" + action = agent.memory.steps[1] + assert isinstance(action, ActionStep) + assert action.tool_results[0].is_error is True + assert "Unknown skill" in action.tool_results[0].content + + +def test_skill_can_be_loaded_from_a_path(tmp_path: Path) -> None: + folder = tmp_path / "greeter" + folder.mkdir() + (folder / "SKILL.md").write_text( + "---\nname: greeter\ndescription: Greet warmly.\n---\nSay hi.\n", + encoding="utf-8", + ) + agent = Agent(model=FakeModel([]), skills=[folder]) + + assert "greeter" in agent.skills + assert "greeter" in agent.instructions + + +# --------------------------------------------------------------------------- # +# Construction guards +# --------------------------------------------------------------------------- # +def test_duplicate_tool_name_raises() -> None: + with pytest.raises(ValueError, match="Duplicate tool name"): + Agent(model=FakeModel([]), tools=[add, add]) + + +def test_max_steps_below_one_raises() -> None: + with pytest.raises(ValueError, match="at least 1"): + Agent(model=FakeModel([]), max_steps=0) + + +async def test_run_max_steps_below_one_raises() -> None: + agent = Agent(model=FakeModel([_assistant(content="unused")])) + + with pytest.raises(ValueError, match="at least 1"): + await agent.run("hi", max_steps=0)