loong-agent 0.0.1__tar.gz

loong_agent-0.0.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: loong-agent
+Version: 0.0.1
+Summary: An open-source, model-agnostic autonomous Agent SDK based on the ReAct framework
+Author: loong-agent
+License: MIT
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: opentelemetry-api>=1.44.0
+Requires-Dist: opentelemetry-sdk>=1.44.0
+Requires-Dist: pytest>=9.1.1 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.16.6 ; extra == 'dev'
+Requires-Dist: mypy>=2.3.1 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1 ; extra == 'docs'
+Requires-Python: >=3.10
+Provides-Extra: dev
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# loong-agent
+
+Agent framework for all — a fully open-source, model-agnostic, pure-code autonomous AI Agent SDK.
+
+Built on the [ReAct](https://arxiv.org/abs/2210.03629) (Reasoning + Acting) framework and inspired by the design of the Claude Agent SDK, it provides a thought-action-observation loop, a tool system, plugins, MCP, Skills, subagents, hooks, permissions, and tracing.
+
+## Features
+
+- **Model-agnostic**: works with any OpenAI-compatible API (OpenAI, local LLaMA.cpp / Ollama / vLLM, etc.).
+- **Pure code implementation**: all logic is written in Python source, with no dependency on commercial closed-source binaries.
+- **ReAct loop**: an autonomous execution engine of Think → Act → Observe.
+- **Rich components**: built-in tools, hook system, permission policies, MCP gateway, Skills, subagents, plugins, and OpenTelemetry tracing.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from loong_agent import FreeAgentOptions, query
+from loong_agent.llm import OpenAICompatibleProvider
+
+async def main():
+    options = FreeAgentOptions(
+        llm=OpenAICompatibleProvider(
+            base_url="https://api.openai.com/v1",
+            api_key="sk-...",
+            model="gpt-4o-mini",
+        ),
+        allowed_tools=["Read", "Write", "Bash", "Grep", "Glob"],
+    )
+
+    async for message in query("Review the code in src/", options=options):
+        if message.type == "assistant":
+            print(f"Agent: {message.text}")
+        elif message.type == "result":
+            print(f"Done! Usage: {message.usage}")
+
+asyncio.run(main())
+```
+
+See [`examples/`](examples/) for more examples.
+
+## Project Structure
+
+```
+src/free_agent/
+├── client.py          # FreeAgentClient / query entry point
+├── loop/              # Agent Loop engine (ReAct loop)
+├── llm/               # LLM adapter layer (OpenAI-compatible)
+├── tools/             # Tool system + built-in tools (Read/Write/Edit/Bash/Grep/Glob)
+├── hooks/             # Hook system
+├── permissions/       # Permission system
+├── mcp/               # MCP gateway (stdio / http / in-process)
+├── skills/            # Skills system (SKILL.md)
+├── subagents/         # Subagent system
+├── plugins/           # Plugin system
+├── tracing/           # OpenTelemetry tracing
+└── types/             # Core types (Message / Options)
+```
+
+## License
+
+MIT

loong_agent-0.0.1/README.md

@@ -0,0 +1,68 @@
+# loong-agent
+
+Agent framework for all — a fully open-source, model-agnostic, pure-code autonomous AI Agent SDK.
+
+Built on the [ReAct](https://arxiv.org/abs/2210.03629) (Reasoning + Acting) framework and inspired by the design of the Claude Agent SDK, it provides a thought-action-observation loop, a tool system, plugins, MCP, Skills, subagents, hooks, permissions, and tracing.
+
+## Features
+
+- **Model-agnostic**: works with any OpenAI-compatible API (OpenAI, local LLaMA.cpp / Ollama / vLLM, etc.).
+- **Pure code implementation**: all logic is written in Python source, with no dependency on commercial closed-source binaries.
+- **ReAct loop**: an autonomous execution engine of Think → Act → Observe.
+- **Rich components**: built-in tools, hook system, permission policies, MCP gateway, Skills, subagents, plugins, and OpenTelemetry tracing.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from loong_agent import FreeAgentOptions, query
+from loong_agent.llm import OpenAICompatibleProvider
+
+async def main():
+    options = FreeAgentOptions(
+        llm=OpenAICompatibleProvider(
+            base_url="https://api.openai.com/v1",
+            api_key="sk-...",
+            model="gpt-4o-mini",
+        ),
+        allowed_tools=["Read", "Write", "Bash", "Grep", "Glob"],
+    )
+
+    async for message in query("Review the code in src/", options=options):
+        if message.type == "assistant":
+            print(f"Agent: {message.text}")
+        elif message.type == "result":
+            print(f"Done! Usage: {message.usage}")
+
+asyncio.run(main())
+```
+
+See [`examples/`](examples/) for more examples.
+
+## Project Structure
+
+```
+src/free_agent/
+├── client.py          # FreeAgentClient / query entry point
+├── loop/              # Agent Loop engine (ReAct loop)
+├── llm/               # LLM adapter layer (OpenAI-compatible)
+├── tools/             # Tool system + built-in tools (Read/Write/Edit/Bash/Grep/Glob)
+├── hooks/             # Hook system
+├── permissions/       # Permission system
+├── mcp/               # MCP gateway (stdio / http / in-process)
+├── skills/            # Skills system (SKILL.md)
+├── subagents/         # Subagent system
+├── plugins/           # Plugin system
+├── tracing/           # OpenTelemetry tracing
+└── types/             # Core types (Message / Options)
+```
+
+## License
+
+MIT

loong_agent-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "loong-agent"
+version = "0.0.1"
+description = "An open-source, model-agnostic autonomous Agent SDK based on the ReAct framework"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.1",
+    "opentelemetry-api>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+]
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "loong-agent"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.6",
+    "mypy>=2.3.1",
+]
+docs = ["mkdocs>=1.6.1"]
+
+[build-system]
+requires = ["uv_build >= 0.12.5, <0.13.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loong_agent"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

loong_agent-0.0.1/pyproject.toml.orig

@@ -0,0 +1,42 @@
+[project]
+name = "loong-agent"
+version = "0.0.1"
+description = "An open-source, model-agnostic autonomous Agent SDK based on the ReAct framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "loong-agent" }]
+dependencies = [
+    "httpx>=0.28.1",
+    "opentelemetry-api>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.6",
+    "mypy>=2.3.1",
+]
+docs = [
+    "mkdocs>=1.6.1",
+]
+
+[build-system]
+requires = ["uv_build >= 0.12.5, <0.13.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loong_agent"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

loong_agent-0.0.1/src/loong_agent/__init__.py

@@ -0,0 +1,64 @@
+"""loong — an open-source, model-agnostic autonomous Agent SDK.
+
+Quick start::
+
+    import asyncio
+    from free_agent import FreeAgentOptions, query
+    from loong_agent.llm import OpenAICompatibleProvider
+
+    options = FreeAgentOptions(
+        llm=OpenAICompatibleProvider(
+            base_url="https://api.openai.com/v1",
+            api_key="sk-...",
+            model="gpt-4o-mini",
+        ),
+        allowed_tools=["Read", "Write", "Bash"],
+    )
+
+    async def main() -> None:
+        async for message in query("Review src/", options=options):
+            print(message.type, message.text)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from loong_agent.client import FreeAgentClient, query
+from loong_agent.loop.engine import AgentLoop
+from loong_agent.subagents.definition import AgentDefinition
+from loong_agent.tools import Tool, tool
+from loong_agent.types import (
+    AssistantMessage,
+    FreeAgentOptions,
+    Message,
+    MessageType,
+    ResultMessage,
+    SystemMessage,
+    ToolCall,
+    ToolResult,
+    Usage,
+    UserMessage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "query",
+    "FreeAgentClient",
+    "FreeAgentOptions",
+    "AgentLoop",
+    "AgentDefinition",
+    "Tool",
+    "tool",
+    "Message",
+    "MessageType",
+    "ToolCall",
+    "ToolResult",
+    "Usage",
+    "SystemMessage",
+    "AssistantMessage",
+    "UserMessage",
+    "ResultMessage",
+    "__version__",
+]

loong_agent-0.0.1/src/loong_agent/client.py

@@ -0,0 +1,89 @@
+"""Public client and convenience entrypoints."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import AsyncIterator, Optional
+
+from loong.loop.engine import AgentLoop
+from loong.types.messages import Message
+from loong.types.options import FreeAgentOptions
+
+
+async def query(
+    prompt: str,
+    options: Optional[FreeAgentOptions] = None,
+) -> AsyncIterator[Message]:
+    """Stream the execution of an agent task, yielding each message in turn.
+
+    Example::
+
+        async for message in query("Summarize src/", options=options):
+            print(message.type, message.text)
+    """
+    if options is None:
+        options = FreeAgentOptions()
+    loop = AgentLoop(options)
+    try:
+        async for message in loop.run(prompt):
+            yield message
+    finally:
+        await loop.aclose()
+
+
+class FreeAgentClient:
+    """Stateful client supporting send/receive streaming and interrupts."""
+
+    def __init__(self, options: Optional[FreeAgentOptions] = None) -> None:
+        self.options = options or FreeAgentOptions()
+        self.loop = AgentLoop(self.options)
+        self._queue: asyncio.Queue = asyncio.Queue()
+        self._task: Optional[asyncio.Task] = None
+
+    async def send(self, prompt: str) -> None:
+        """Start processing ``prompt``; results are read via :meth:`receive`."""
+        if self._task is not None and not self._task.done():
+            raise RuntimeError("A request is already in progress.")
+        self._task = asyncio.create_task(self._run(prompt))
+
+    async def _run(self, prompt: str) -> None:
+        try:
+            async for message in self.loop.run(prompt):
+                await self._queue.put(message)
+        except Exception as exc:  # noqa: BLE001
+            await self._queue.put(
+                Message.result(text=f"Error: {exc}", is_error=True)
+            )
+        finally:
+            await self._queue.put(_SENTINEL)
+
+    async def receive(self) -> AsyncIterator[Message]:
+        """Yield messages produced by the current request until completion."""
+        while True:
+            message = await self._queue.get()
+            if message is _SENTINEL:
+                break
+            yield message
+
+    async def interrupt(self) -> None:
+        """Cancel the in-flight request."""
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        await self._queue.put(_SENTINEL)
+
+    async def close(self) -> None:
+        await self.loop.aclose()
+
+
+class _Sentinel:
+    pass
+
+
+_SENTINEL = _Sentinel()
+
+
+__all__ = ["query", "FreeAgentClient"]

loong_agent-0.0.1/src/loong_agent/hooks/__init__.py

@@ -0,0 +1,14 @@
+"""Hook system."""
+
+from loong.hooks.events import HookContext, HookEvent, HookOutput
+from loong.hooks.matcher import HookMatcher
+from loong.hooks.registry import Hook, HookRegistry
+
+__all__ = [
+    "HookEvent",
+    "HookContext",
+    "HookOutput",
+    "HookMatcher",
+    "Hook",
+    "HookRegistry",
+]

loong_agent-0.0.1/src/loong_agent/hooks/events.py

@@ -0,0 +1,57 @@
+"""Hook event definitions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class HookEvent(str, Enum):
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    SUBAGENT_START = "SubagentStart"
+    SUBAGENT_STOP = "SubagentStop"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    IDLE = "Idle"
+
+
+@dataclass
+class HookContext:
+    """Metadata passed to hook callbacks."""
+
+    session_id: Optional[str] = None
+    cwd: Optional[str] = None
+    model: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookOutput:
+    """Return value of a hook callback.
+
+    Attributes:
+        permission_decision: ``"allow"``, ``"deny"`` or ``"ask"``.
+        updated_input: Replacement input for the operation being hooked.
+        injected_context: Additional context injected into the conversation.
+        output: Optional message to surface to the caller.
+        stop_reason: Optional reason string if the hook stops the session.
+    """
+
+    permission_decision: str = "allow"
+    updated_input: Optional[Dict[str, Any]] = None
+    injected_context: Optional[str] = None
+    output: Optional[str] = None
+    stop_reason: Optional[str] = None
+
+    @classmethod
+    def allow(cls, **kwargs: Any) -> "HookOutput":
+        return cls(permission_decision="allow", **kwargs)
+
+    @classmethod
+    def deny(cls, reason: str = "", **kwargs: Any) -> "HookOutput":
+        return cls(permission_decision="deny", output=reason or None, **kwargs)
+
+
+__all__ = ["HookEvent", "HookContext", "HookOutput"]

loong_agent-0.0.1/src/loong_agent/hooks/matcher.py

@@ -0,0 +1,33 @@
+"""Hook matching utilities."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from loong.hooks.events import HookEvent
+
+
+@dataclass
+class HookMatcher:
+    """Filters whether a hook should fire for a given event/input.
+
+    ``matcher``, when provided, is a regular expression tested against the
+    string form of the hook input (e.g. a tool name).
+    """
+
+    event: HookEvent
+    matcher: Optional[str] = None
+
+    def matches(self, event: HookEvent, target: Optional[str] = None) -> bool:
+        if self.event != event:
+            return False
+        if self.matcher is None:
+            return True
+        if target is None:
+            return False
+        return re.search(self.matcher, target) is not None
+
+
+__all__ = ["HookMatcher"]

loong_agent-0.0.1/src/loong_agent/hooks/registry.py

@@ -0,0 +1,124 @@
+"""Hook registration and dispatch."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from loong.hooks.events import HookContext, HookEvent, HookOutput
+from loong.hooks.matcher import HookMatcher
+
+HookCallback = Callable[..., Any]
+
+
+@dataclass
+class Hook:
+    """A registered hook callback with an optional matcher."""
+
+    callback: HookCallback
+    matcher: Optional[HookMatcher] = None
+
+    async def invoke(
+        self,
+        event: HookEvent,
+        input_data: Optional[Dict[str, Any]] = None,
+        tool_use_id: Optional[str] = None,
+        context: Optional[HookContext] = None,
+    ) -> Optional[HookOutput]:
+        if self.matcher is not None and not self.matcher.matches(
+            event, _target(input_data)
+        ):
+            return None
+
+        signature = inspect.signature(self.callback)
+        accepts_var_kw = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in signature.parameters.values()
+        )
+        available: Dict[str, Any] = {
+            "input_data": input_data or {},
+            "tool_use_id": tool_use_id,
+            "context": context or HookContext(),
+        }
+        kwargs: Dict[str, Any] = {
+            name: value
+            for name, value in available.items()
+            if name in signature.parameters or accepts_var_kw
+        }
+
+        result = self.callback(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        if result is None:
+            return None
+        if isinstance(result, HookOutput):
+            return result
+        # Allow callbacks to return a plain permission string.
+        if isinstance(result, str):
+            return HookOutput(permission_decision=result)
+        return HookOutput(**result) if isinstance(result, dict) else None
+
+
+def _target(input_data: Optional[Dict[str, Any]]) -> Optional[str]:
+    if not input_data:
+        return None
+    for key in ("tool_name", "name", "event"):
+        if key in input_data:
+            return str(input_data[key])
+    return None
+
+
+class HookRegistry:
+    """Collects hooks and dispatches events to matching callbacks."""
+
+    def __init__(self) -> None:
+        self._hooks: List[Hook] = []
+
+    def register(self, callback: HookCallback, matcher: Optional[HookMatcher] = None) -> None:
+        self._hooks.append(Hook(callback=callback, matcher=matcher))
+
+    def register_for_event(
+        self,
+        event: HookEvent,
+        callback: HookCallback,
+        matcher: Optional[str] = None,
+    ) -> None:
+        self._hooks.append(
+            Hook(callback=callback, matcher=HookMatcher(event=event, matcher=matcher))
+        )
+
+    def clear(self) -> None:
+        self._hooks.clear()
+
+    async def dispatch(
+        self,
+        event: HookEvent,
+        input_data: Optional[Dict[str, Any]] = None,
+        tool_use_id: Optional[str] = None,
+        context: Optional[HookContext] = None,
+    ) -> List[HookOutput]:
+        """Invoke every matching hook and return their outputs."""
+        outputs: List[HookOutput] = []
+        for hook in self._hooks:
+            out = await hook.invoke(event, input_data, tool_use_id, context)
+            if out is not None:
+                outputs.append(out)
+        return outputs
+
+    @staticmethod
+    def from_config(config: dict[str, list[HookCallback]]) -> "HookRegistry":
+        """Build a registry from an ``{event_name: [callbacks]}`` mapping."""
+        registry = HookRegistry()
+        for event_name, callbacks in config.items():
+            try:
+                event = HookEvent(event_name)
+            except ValueError:
+                # Unknown events are registered with no matcher and dispatched
+                # only when an explicit event filter matches the raw name.
+                continue
+            for callback in callbacks:
+                registry.register_for_event(event, callback)
+        return registry
+
+
+__all__ = ["Hook", "HookRegistry", "HookCallback"]

loong_agent-0.0.1/src/loong_agent/llm/__init__.py

@@ -0,0 +1,19 @@
+"""LLM adapter layer."""
+
+from loong.llm.base import ChatResponse, LLMProvider, ToolDefinition
+from loong.llm.openai_compatible import OpenAICompatibleProvider
+from loong.llm.registry import (
+    available_providers,
+    get_provider,
+    register_provider,
+)
+
+__all__ = [
+    "LLMProvider",
+    "ChatResponse",
+    "ToolDefinition",
+    "OpenAICompatibleProvider",
+    "register_provider",
+    "get_provider",
+    "available_providers",
+]