kiarina-agi-runner 2.14.0__tar.gz

kiarina_agi_runner-2.14.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# uv
+.uv_cache/
+
+# Virtual environments & config
+.venv/
+.env
+
+# OS
+.DS_Store
+
+# Project specific
+*.log
+tmp/
+**/test_settings.yaml
+
+# mise tasks (always include)
+!.mise/tasks/
+!.mise/tasks/**
+
+# Test assets downloaded via mise
+tests/assets/

kiarina_agi_runner-2.14.0/.mise/tasks/package/current

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+#MISE description="Print the current package name"
+
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+basename "$(dirname "$(dirname "$(dirname "$script_dir")")")"

kiarina_agi_runner-2.14.0/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    "python.testing.pytestArgs": [
+        "tests",
+        "-rs",
+        "-v"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

kiarina_agi_runner-2.14.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.14.0] - 2026-07-10
+
+### Added
+
+- Add agent execution, task runner, and structured output helper APIs for AI agents.
+
+## [2.13.0] - 2026-07-10
+
+### Added
+
+- Initial release.

kiarina_agi_runner-2.14.0/Makefile

@@ -0,0 +1,17 @@
+.PHONY: format lint test build clean check
+.DEFAULT_GOAL := check
+
+format:
+	mise run format
+lint:
+	mise run lint
+test:
+	mise run test
+build:
+	mise run build
+clean:
+	mise run clean
+check:
+	mise run format
+	mise run lint
+	mise run test --coverage

kiarina_agi_runner-2.14.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: kiarina-agi-runner
+Version: 2.14.0
+Summary: Agent, task runner, and structured output helpers for AI agents
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-agi-runner/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-agi-runner#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+Keywords: agents,ai,runner,structured-output,tasks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: kiarina-agi-base>=2.7.0
+Requires-Dist: kiarina-agi-data-builder>=2.13.0
+Requires-Dist: kiarina-agi-data>=2.7.0
+Requires-Dist: kiarina-agi-file>=2.8.0
+Requires-Dist: kiarina-agi-flow>=2.11.0
+Requires-Dist: kiarina-agi-text>=2.8.0
+Requires-Dist: kiarina-agi-tool>=2.12.0
+Requires-Dist: kiarina-utils-common>=2.8.0
+Requires-Dist: kiarina-utils-file>=2.3.1
+Requires-Dist: pydantic-settings-manager>=3.2.0
+Requires-Dist: pydantic-settings<3,>=2.10.1
+Requires-Dist: pydantic<3,>=2.11.7
+Description-Content-Type: text/markdown
+
+# kiarina-agi-runner
+
+English | [日本語](README.ja.md)
+
+## What is this?
+
+`kiarina-agi-runner` provides agent execution, task runners, and structured output helpers for AI agents.
+
+## Dependencies
+
+| Package | Version | License |
+| --- | --- | --- |
+| [kiarina-agi-base](../kiarina-agi-base/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data](../kiarina-agi-data/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data-builder](../kiarina-agi-data-builder/) | `>=2.13.0` | MIT |
+| [kiarina-agi-file](../kiarina-agi-file/) | `>=2.8.0` | MIT |
+| [kiarina-agi-flow](../kiarina-agi-flow/) | `>=2.11.0` | MIT |
+| [kiarina-agi-text](../kiarina-agi-text/) | `>=2.8.0` | MIT |
+| [kiarina-agi-tool](../kiarina-agi-tool/) | `>=2.12.0` | MIT |
+| [kiarina-utils-common](../kiarina-utils-common/) | `>=2.8.0` | MIT |
+| [kiarina-utils-file](../kiarina-utils-file/) | `>=2.3.1` | MIT |
+| [Pydantic](https://github.com/pydantic/pydantic) | `>=2.11.7,<3` | MIT |
+| [pydantic-settings](https://github.com/pydantic/pydantic-settings) | `>=2.10.1,<3` | MIT |
+| [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) | `>=3.2.0` | MIT |

kiarina_agi_runner-2.14.0/README.ja.md

@@ -0,0 +1,24 @@
+# kiarina-agi-runner
+
+[English](README.md) | 日本語
+
+## What is this?
+
+`kiarina-agi-runner` は、AI agent の agent 実行、task runner、structured output helper を構成するための package です。
+
+## Dependencies
+
+| Package | Version | License |
+| --- | --- | --- |
+| [kiarina-agi-base](../kiarina-agi-base/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data](../kiarina-agi-data/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data-builder](../kiarina-agi-data-builder/) | `>=2.13.0` | MIT |
+| [kiarina-agi-file](../kiarina-agi-file/) | `>=2.8.0` | MIT |
+| [kiarina-agi-flow](../kiarina-agi-flow/) | `>=2.11.0` | MIT |
+| [kiarina-agi-text](../kiarina-agi-text/) | `>=2.8.0` | MIT |
+| [kiarina-agi-tool](../kiarina-agi-tool/) | `>=2.12.0` | MIT |
+| [kiarina-utils-common](../kiarina-utils-common/) | `>=2.8.0` | MIT |
+| [kiarina-utils-file](../kiarina-utils-file/) | `>=2.3.1` | MIT |
+| [Pydantic](https://github.com/pydantic/pydantic) | `>=2.11.7,<3` | MIT |
+| [pydantic-settings](https://github.com/pydantic/pydantic-settings) | `>=2.10.1,<3` | MIT |
+| [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) | `>=3.2.0` | MIT |

kiarina_agi_runner-2.14.0/README.md

@@ -0,0 +1,24 @@
+# kiarina-agi-runner
+
+English | [日本語](README.ja.md)
+
+## What is this?
+
+`kiarina-agi-runner` provides agent execution, task runners, and structured output helpers for AI agents.
+
+## Dependencies
+
+| Package | Version | License |
+| --- | --- | --- |
+| [kiarina-agi-base](../kiarina-agi-base/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data](../kiarina-agi-data/) | `>=2.7.0` | MIT |
+| [kiarina-agi-data-builder](../kiarina-agi-data-builder/) | `>=2.13.0` | MIT |
+| [kiarina-agi-file](../kiarina-agi-file/) | `>=2.8.0` | MIT |
+| [kiarina-agi-flow](../kiarina-agi-flow/) | `>=2.11.0` | MIT |
+| [kiarina-agi-text](../kiarina-agi-text/) | `>=2.8.0` | MIT |
+| [kiarina-agi-tool](../kiarina-agi-tool/) | `>=2.12.0` | MIT |
+| [kiarina-utils-common](../kiarina-utils-common/) | `>=2.8.0` | MIT |
+| [kiarina-utils-file](../kiarina-utils-file/) | `>=2.3.1` | MIT |
+| [Pydantic](https://github.com/pydantic/pydantic) | `>=2.11.7,<3` | MIT |
+| [pydantic-settings](https://github.com/pydantic/pydantic-settings) | `>=2.10.1,<3` | MIT |
+| [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) | `>=3.2.0` | MIT |

kiarina_agi_runner-2.14.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "kiarina-agi-runner"
+version = "2.14.0"
+description = "Agent, task runner, and structured output helpers for AI agents"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "kiarina", email = "kiarinadawa@gmail.com" }]
+maintainers = [{ name = "kiarina", email = "kiarinadawa@gmail.com" }]
+keywords = ["ai", "agents", "runner", "tasks", "structured-output"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "kiarina-agi-base>=2.7.0",
+    "kiarina-agi-data>=2.7.0",
+    "kiarina-agi-data-builder>=2.13.0",
+    "kiarina-agi-file>=2.8.0",
+    "kiarina-agi-flow>=2.11.0",
+    "kiarina-agi-text>=2.8.0",
+    "kiarina-agi-tool>=2.12.0",
+    "kiarina-utils-common>=2.8.0",
+    "kiarina-utils-file>=2.3.1",
+    "pydantic>=2.11.7,<3",
+    "pydantic-settings>=2.10.1,<3",
+    "pydantic-settings-manager>=3.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kiarina/kiarina-python"
+Repository = "https://github.com/kiarina/kiarina-python"
+Issues = "https://github.com/kiarina/kiarina-python/issues"
+Changelog = "https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-agi-runner/CHANGELOG.md"
+Documentation = "https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-agi-runner#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kiarina"]

kiarina_agi_runner-2.14.0/src/kiarina/agi/agent/__init__.py

@@ -0,0 +1,35 @@
+from ._exceptions.missing_tools_error import MissingToolsError
+from ._helpers.invoke_agent import invoke_agent
+from ._helpers.run_agent import run_agent
+from ._helpers.stream_agent import stream_agent
+from ._models.base_agent import BaseAgent
+from ._schemas.agent_context import AgentContext
+from ._services.agent_registry import agent_registry
+from ._settings import AgentSettings, settings_manager
+from ._types.agent import Agent
+from ._types.agent_name import AgentName
+from ._types.agent_options import AgentOptions
+from ._types.agent_specifier import AgentSpecifier
+
+__all__ = [
+    # ._helpers
+    "invoke_agent",
+    "run_agent",
+    "stream_agent",
+    # ._exceptions
+    "MissingToolsError",
+    # ._models
+    "BaseAgent",
+    # ._schemas
+    "AgentContext",
+    # ._services
+    "agent_registry",
+    # ._settings
+    "AgentSettings",
+    "settings_manager",
+    # ._types
+    "Agent",
+    "AgentName",
+    "AgentOptions",
+    "AgentSpecifier",
+]

kiarina_agi_runner-2.14.0/src/kiarina/agi/agent/_exceptions/missing_tools_error.py

@@ -0,0 +1,8 @@
+from kiarina.agi.tool_info import ToolName
+
+
+class MissingToolsError(Exception):
+    def __init__(self, tool_names: list[ToolName]) -> None:
+        unique_tool_names = list(dict.fromkeys(tool_names))
+        self.tool_names: list[ToolName] = unique_tool_names
+        super().__init__(f"Missing tools: {', '.join(unique_tool_names)}")

kiarina_agi_runner-2.14.0/src/kiarina/agi/agent/_helpers/invoke_agent.py

@@ -0,0 +1,43 @@
+import asyncio
+from collections.abc import AsyncIterator
+from typing import Any
+
+from kiarina.agi.chat_model import ChatOptions
+from kiarina.agi.cost_recorder import CostRecorder
+from kiarina.agi.event import Event
+from kiarina.agi.history import History
+from kiarina.agi.prompt import PromptOptions
+from kiarina.agi.run_context import RunContext
+from kiarina.agi.tool import ToolOptions
+from kiarina.agi.workflow import WorkflowOptions
+
+from .._types.agent_options import AgentOptions
+from .run_agent import run_agent
+
+
+async def invoke_agent(
+    history: History,
+    *,
+    chat_options: ChatOptions | None = None,
+    prompt_options: PromptOptions | None = None,
+    workflow_options: WorkflowOptions | None = None,
+    tool_options: ToolOptions | None = None,
+    agent_options: AgentOptions | None = None,
+    cost_recorder: CostRecorder | None = None,
+    run_context: RunContext,
+    stop_event: asyncio.Event | None = None,
+    **kwargs: Any,
+) -> AsyncIterator[Event]:
+    async for event in run_agent(
+        history,
+        chat_options={**(chat_options or {}), "streaming": False},
+        prompt_options=prompt_options,
+        workflow_options=workflow_options,
+        tool_options=tool_options,
+        agent_options=agent_options,
+        cost_recorder=cost_recorder,
+        run_context=run_context,
+        stop_event=stop_event,
+        **kwargs,
+    ):
+        yield event

kiarina_agi_runner-2.14.0/src/kiarina/agi/agent/_helpers/run_agent.py

@@ -0,0 +1,206 @@
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from kiarina.agi.chat_limits import ChatLimits
+from kiarina.agi.chat_model import ChatOptions
+from kiarina.agi.cost_recorder import CostRecorder
+from kiarina.agi.event import Event
+from kiarina.agi.history import History
+from kiarina.agi.message import AIMessage, Message, ToolMessage
+from kiarina.agi.prompt import PromptOptions
+from kiarina.agi.run_context import RunContext
+from kiarina.agi.tool import ToolOptions
+from kiarina.agi.workflow import WorkflowOptions
+
+from .._exceptions.missing_tools_error import MissingToolsError
+from .._schemas.agent_context import AgentContext
+from .._services.agent_registry import agent_registry
+from .._settings import settings_manager
+from .._types.agent import Agent
+from .._types.agent_options import AgentOptions
+
+logger = logging.getLogger(__name__)
+
+
+async def run_agent(
+    history: History,
+    *,
+    chat_options: ChatOptions | None = None,
+    prompt_options: PromptOptions | None = None,
+    workflow_options: WorkflowOptions | None = None,
+    tool_options: ToolOptions | None = None,
+    agent_options: AgentOptions | None = None,
+    cost_recorder: CostRecorder | None = None,
+    run_context: RunContext,
+    stop_event: asyncio.Event | None = None,
+    **kwargs: Any,
+) -> AsyncIterator[Event]:
+    agent_options = agent_options or {}
+
+    agent = agent_options.get("agent")
+
+    if not isinstance(agent, Agent):
+        agent = agent_registry.resolve(agent)
+
+    file_limits = agent_options.get("file_limits")
+
+    if not isinstance(file_limits, ChatLimits):
+        file_limits = ChatLimits.from_specifier(file_limits or "")
+
+    max_iterations = (
+        agent_options.get("max_iterations") or settings_manager.settings.max_iterations
+    )
+
+    until_end = agent_options.get("until_end") or False
+    until_tool_calls = agent_options.get("until_tool_calls") or []
+    until_tool_runs = agent_options.get("until_tool_runs") or []
+
+    ctx = AgentContext.create(
+        file_limits=file_limits,
+        chat_options=chat_options,
+        prompt_options=prompt_options,
+        workflow_options=workflow_options,
+        tool_options=tool_options,
+        cost_recorder=cost_recorder,
+        run_context=run_context,
+        **kwargs,
+    )
+
+    iterations = 0
+
+    while True:
+        if stop_event is not None and stop_event.is_set():
+            logger.debug("Agent loop stopped by stop event")
+            break
+
+        if _is_conversation_end(history):
+            break
+
+        if _is_iteration_end(history, agent_options, iterations, max_iterations):
+            break
+
+        iterations += 1
+        new_events: list[Event] = []
+        ctx.run_context = run_context.with_metadata(
+            loop=_format_loop(
+                iterations=iterations,
+                max_iterations=max_iterations,
+                until_end=until_end,
+                until_tool_calls=until_tool_calls,
+                until_tool_runs=until_tool_runs,
+            ),
+            agent=str(agent),
+        )
+
+        try:
+            async for event in _run_agent_iteration(ctx, history, agent):
+                yield event
+                new_events.append(event)
+
+        except MissingToolsError as e:
+            logger.debug(f"Missing tools called: {', '.join(e.tool_names)}")
+            break
+
+        last_message = _get_last_message_from_events(new_events)
+
+        if last_message is None:
+            break
+
+        if isinstance(last_message, ToolMessage) and last_message.return_direct:
+            break
+
+        if until_tool_calls and isinstance(last_message, AIMessage):
+            if any(
+                tool_call.name in until_tool_calls
+                for tool_call in last_message.tool_calls
+            ):
+                logger.debug("Until tool calls reached")
+                break
+
+        if until_tool_runs and isinstance(last_message, ToolMessage):
+            if last_message.tool_name in until_tool_runs:
+                logger.debug("Until tool runs reached")
+                break
+
+
+async def _run_agent_iteration(
+    ctx: AgentContext,
+    history: History,
+    agent: Agent,
+) -> AsyncIterator[Event]:
+    async for event in agent.pre_run(ctx, history):
+        yield event
+
+    async for event in agent.run(ctx, history):
+        yield event
+
+    async for event in agent.post_run(ctx, history):
+        yield event
+
+
+def _is_conversation_end(history: History) -> bool:
+    message = _get_last_message(history)
+    return isinstance(message, AIMessage) and not message.tool_calls
+
+
+def _is_iteration_end(
+    history: History,
+    agent_options: AgentOptions,
+    iterations: int,
+    max_iterations: int,
+) -> bool:
+    return iterations >= max_iterations and not _should_continue_until_end(
+        history,
+        agent_options,
+    )
+
+
+def _should_continue_until_end(
+    history: History,
+    agent_options: AgentOptions,
+) -> bool:
+    return agent_options.get("until_end", False) and _is_last_tool_call(history)
+
+
+def _is_last_tool_call(history: History) -> bool:
+    message = _get_last_message(history)
+    return isinstance(message, AIMessage) and bool(message.tool_calls)
+
+
+def _format_loop(
+    *,
+    iterations: int,
+    max_iterations: int,
+    until_end: bool,
+    until_tool_calls: list[str],
+    until_tool_runs: list[str],
+) -> str:
+    return (
+        f"{iterations}/{max_iterations}"
+        f"{' until_end' if until_end else ''}"
+        f"{' until_tool_calls(' + ','.join(until_tool_calls) + ')' if until_tool_calls else ''}"
+        f"{' until_tool_runs(' + ','.join(until_tool_runs) + ')' if until_tool_runs else ''}"
+    ).strip()
+
+
+def _get_last_message(history: History) -> Message | None:
+    messages = history.get_messages()
+
+    if not messages:
+        return None
+
+    return messages[-1]
+
+
+def _get_last_message_from_events(events: list[Event]) -> Message | None:
+    for event in reversed(events):
+        if (
+            event.type == "human_message"
+            or event.type == "ai_message"
+            or event.type == "tool_message"
+        ):
+            return event.message
+
+    return None

kiarina_agi_runner-2.14.0/src/kiarina/agi/agent/_helpers/stream_agent.py

@@ -0,0 +1,43 @@
+import asyncio
+from collections.abc import AsyncIterator
+from typing import Any
+
+from kiarina.agi.chat_model import ChatOptions
+from kiarina.agi.cost_recorder import CostRecorder
+from kiarina.agi.event import Event
+from kiarina.agi.history import History
+from kiarina.agi.prompt import PromptOptions
+from kiarina.agi.run_context import RunContext
+from kiarina.agi.tool import ToolOptions
+from kiarina.agi.workflow import WorkflowOptions
+
+from .._types.agent_options import AgentOptions
+from .run_agent import run_agent
+
+
+async def stream_agent(
+    history: History,
+    *,
+    chat_options: ChatOptions | None = None,
+    prompt_options: PromptOptions | None = None,
+    workflow_options: WorkflowOptions | None = None,
+    tool_options: ToolOptions | None = None,
+    agent_options: AgentOptions | None = None,
+    cost_recorder: CostRecorder | None = None,
+    run_context: RunContext,
+    stop_event: asyncio.Event | None = None,
+    **kwargs: Any,
+) -> AsyncIterator[Event]:
+    async for event in run_agent(
+        history,
+        chat_options={**(chat_options or {}), "streaming": True},
+        prompt_options=prompt_options,
+        workflow_options=workflow_options,
+        tool_options=tool_options,
+        agent_options=agent_options,
+        cost_recorder=cost_recorder,
+        run_context=run_context,
+        stop_event=stop_event,
+        **kwargs,
+    ):
+        yield event