easyharness 0.1.0__tar.gz

easyharness-0.1.0/LICENSE

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

easyharness-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: easyharness
+Version: 0.1.0
+Summary: A minimal Python SDK for agent loops, with streaming events, clean tool contracts, and zero ceremony.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: litellm<=1.89.3,>=1.75.9
+Requires-Dist: prompt4py>=0.0.6
+Requires-Dist: vortezwohl>=0.1.3
+Requires-Dist: strands-agents-tools>=0.8.2
+Requires-Dist: strands-agents[litellm]>=1.45.0
+Requires-Dist: fileglide>=0.0.1
+Dynamic: license-file
+
+<div align="center">
+  <h1>EasyHarness</h1>
+  <p>
+    <strong>
+      A minimal Python SDK for agent loops, with streaming events, clean tool contracts, and zero ceremony.
+    </strong>
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.10+" />
+    <a href="https://github.com/vortezwohl/fileglide">
+      <img src="https://img.shields.io/badge/fileglide-2563EB?logo=github&amp;logoColor=white" alt="FileGlide" />
+    </a>
+    <a href="https://github.com/strands-agents/harness-sdk">
+      <img src="https://img.shields.io/badge/strands%20agents-0F766E?logo=github&amp;logoColor=white" alt="Strands Agents" />
+    </a>
+    <a href="https://github.com/BerriAI/litellm">
+      <img src="https://img.shields.io/badge/litellm-7C3AED?logo=github&amp;logoColor=white" alt="LiteLLM" />
+    </a>
+  </p>
+  <p>
+    <sub>Small public surface. Strong defaults. Explicit control.</sub>
+  </p>
+</div>
+
+## Why EasyHarness
+
+EasyHarness is designed for local agent workflows where a tiny SDK surface
+matters more than a large framework.
+
+It works well for coding agents, but it is not limited to them. Any agent that
+benefits from strict tool contracts, streaming events, and explicit runtime
+control can use the same SDK surface.
+
+It gives you:
+
+- A single primary runtime entry point through `Agent`
+- Strict tool metadata and output contracts through `tool` and `ToolOutput`
+- A unified streaming event model for thinking, tool, assistant, compression,
+  and system events
+- An official FileGlide-backed filesystem toolset that can be auto-loaded by
+  default or scoped explicitly
+
+## Public Surface
+
+The root package intentionally exposes only five public names:
+
+- `Agent`
+- `ModelConfig`
+- `AgentEvent`
+- `ToolOutput`
+- `tool`
+
+Everything else stays behind internal modules or the explicit
+`easyharness.toolset` package.
+
+## Typical Usage
+
+### 1. Define a tool and run an agent
+
+```python
+from easyharness import Agent, ModelConfig, ToolOutput, tool
+
+
+@tool(
+    name="ping_tool",
+    purpose="Return a fixed response for a minimal tool-flow check.",
+    when_to_use=(
+        "Use this when the model needs a trivial tool call to verify that the "
+        "tool pipeline is available."
+    ),
+    parameters={},
+    returns="A fixed pong response.",
+    common_failures=["This tool does not fail under normal conditions."],
+)
+def ping_tool() -> ToolOutput:
+    return ToolOutput(
+        data={"value": "pong"},
+        model_text="pong",
+        preview="pong",
+        detail='{"value": "pong"}',
+    )
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a precise agent.",
+    tools=[ping_tool],
+)
+
+print(agent.run("Call the ping tool and confirm that the tool pipeline works."))
+```
+
+### 2. Use the default FileGlide integration
+
+`Agent` can auto-load the official FileGlide-backed toolset, so the shortest
+agent setup does not need a manual `tools=[...]` list.
+
+```python
+from easyharness import Agent, ModelConfig
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+)
+
+print(
+    agent.run(
+        "List the workspace, read pyproject.toml, and summarize the SDK shape."
+    )
+)
+```
+
+<details>
+  <summary><strong>Official default FileGlide tools</strong></summary>
+
+  <ul>
+    <li><code>fileglide_list_tree</code></li>
+    <li><code>fileglide_search_paths</code></li>
+    <li><code>fileglide_read_text</code></li>
+    <li><code>fileglide_search_text</code></li>
+    <li><code>fileglide_edit_text</code></li>
+    <li><code>fileglide_manage_paths</code></li>
+    <li><code>fileglide_inspect_path</code></li>
+  </ul>
+</details>
+
+### 3. Disable the default FileGlide tools
+
+If you want a stricter default runtime with no filesystem tool auto-loading,
+disable it explicitly.
+
+```python
+from easyharness import Agent, ModelConfig
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+    enable_fileglide=False,
+)
+```
+
+### 4. Build a scoped official FileGlide toolset
+
+When you need explicit control over the filesystem scope, disable the default
+auto-load and pass a scoped official toolset from `easyharness.toolset`.
+
+```python
+from easyharness import Agent, ModelConfig
+from easyharness.toolset import build_fileglide_tools
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+    enable_fileglide=False,
+    tools=build_fileglide_tools(default_root="D:/Projects/PythonProjects/EasyHarness"),
+)
+```
+
+`build_fileglide_tools(default_root=...)` creates the official scoped toolset. Paths
+that escape the configured root are rejected by FileGlide scope protection.
+
+Each official `fileglide_*` tool also accepts an optional `root` argument for
+that single call. When provided, it overrides the builder's default root
+without additional SDK-level path-range restrictions.
+
+```python
+tools = build_fileglide_tools(default_root="D:/Projects/PythonProjects/EasyHarness")
+tool_map = {tool.tool_name: tool for tool in tools}
+
+result = tool_map["fileglide_read_text"](
+    target="EasyHarness/pyproject.toml",
+    root="D:/Projects/PythonProjects",
+)
+```
+
+## Event Stream
+
+`agent.stream(prompt)` yields a unified `AgentEvent` stream. The public event
+kinds are:
+
+- `thinking`
+- `tool`
+- `assistant`
+- `compress`
+- `system`
+
+Each event uses the same status vocabulary:
+
+- `started`
+- `delta`
+- `completed`
+- `failed`
+
+```python
+for event in agent.stream("Inspect the workspace and explain the next step."):
+    print(event.kind, event.status, event.text)
+```
+
+## Design Boundaries
+
+EasyHarness is intentionally small. v1 does not try to solve:
+
+- UI components
+- Environment-variable orchestration layers
+- Plugin platforms
+- Multi-agent orchestration
+- Root-package re-export sprawl for toolset builders
+
+## Summary
+
+EasyHarness is most useful when you want:
+
+- A minimal `Agent` API
+- Strict tool definitions
+- Streaming runtime visibility
+- A practical, official FileGlide-backed filesystem toolset
+
+If that is your shape of problem, the shortest path is:
+
+1. Create an `Agent`
+2. Define tools with `@tool(...)`
+3. Use the default FileGlide integration or pass a scoped official toolset

easyharness-0.1.0/README.md

@@ -0,0 +1,237 @@
+<div align="center">
+  <h1>EasyHarness</h1>
+  <p>
+    <strong>
+      A minimal Python SDK for agent loops, with streaming events, clean tool contracts, and zero ceremony.
+    </strong>
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.10+" />
+    <a href="https://github.com/vortezwohl/fileglide">
+      <img src="https://img.shields.io/badge/fileglide-2563EB?logo=github&amp;logoColor=white" alt="FileGlide" />
+    </a>
+    <a href="https://github.com/strands-agents/harness-sdk">
+      <img src="https://img.shields.io/badge/strands%20agents-0F766E?logo=github&amp;logoColor=white" alt="Strands Agents" />
+    </a>
+    <a href="https://github.com/BerriAI/litellm">
+      <img src="https://img.shields.io/badge/litellm-7C3AED?logo=github&amp;logoColor=white" alt="LiteLLM" />
+    </a>
+  </p>
+  <p>
+    <sub>Small public surface. Strong defaults. Explicit control.</sub>
+  </p>
+</div>
+
+## Why EasyHarness
+
+EasyHarness is designed for local agent workflows where a tiny SDK surface
+matters more than a large framework.
+
+It works well for coding agents, but it is not limited to them. Any agent that
+benefits from strict tool contracts, streaming events, and explicit runtime
+control can use the same SDK surface.
+
+It gives you:
+
+- A single primary runtime entry point through `Agent`
+- Strict tool metadata and output contracts through `tool` and `ToolOutput`
+- A unified streaming event model for thinking, tool, assistant, compression,
+  and system events
+- An official FileGlide-backed filesystem toolset that can be auto-loaded by
+  default or scoped explicitly
+
+## Public Surface
+
+The root package intentionally exposes only five public names:
+
+- `Agent`
+- `ModelConfig`
+- `AgentEvent`
+- `ToolOutput`
+- `tool`
+
+Everything else stays behind internal modules or the explicit
+`easyharness.toolset` package.
+
+## Typical Usage
+
+### 1. Define a tool and run an agent
+
+```python
+from easyharness import Agent, ModelConfig, ToolOutput, tool
+
+
+@tool(
+    name="ping_tool",
+    purpose="Return a fixed response for a minimal tool-flow check.",
+    when_to_use=(
+        "Use this when the model needs a trivial tool call to verify that the "
+        "tool pipeline is available."
+    ),
+    parameters={},
+    returns="A fixed pong response.",
+    common_failures=["This tool does not fail under normal conditions."],
+)
+def ping_tool() -> ToolOutput:
+    return ToolOutput(
+        data={"value": "pong"},
+        model_text="pong",
+        preview="pong",
+        detail='{"value": "pong"}',
+    )
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a precise agent.",
+    tools=[ping_tool],
+)
+
+print(agent.run("Call the ping tool and confirm that the tool pipeline works."))
+```
+
+### 2. Use the default FileGlide integration
+
+`Agent` can auto-load the official FileGlide-backed toolset, so the shortest
+agent setup does not need a manual `tools=[...]` list.
+
+```python
+from easyharness import Agent, ModelConfig
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+)
+
+print(
+    agent.run(
+        "List the workspace, read pyproject.toml, and summarize the SDK shape."
+    )
+)
+```
+
+<details>
+  <summary><strong>Official default FileGlide tools</strong></summary>
+
+  <ul>
+    <li><code>fileglide_list_tree</code></li>
+    <li><code>fileglide_search_paths</code></li>
+    <li><code>fileglide_read_text</code></li>
+    <li><code>fileglide_search_text</code></li>
+    <li><code>fileglide_edit_text</code></li>
+    <li><code>fileglide_manage_paths</code></li>
+    <li><code>fileglide_inspect_path</code></li>
+  </ul>
+</details>
+
+### 3. Disable the default FileGlide tools
+
+If you want a stricter default runtime with no filesystem tool auto-loading,
+disable it explicitly.
+
+```python
+from easyharness import Agent, ModelConfig
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+    enable_fileglide=False,
+)
+```
+
+### 4. Build a scoped official FileGlide toolset
+
+When you need explicit control over the filesystem scope, disable the default
+auto-load and pass a scoped official toolset from `easyharness.toolset`.
+
+```python
+from easyharness import Agent, ModelConfig
+from easyharness.toolset import build_fileglide_tools
+
+
+agent = Agent(
+    model=ModelConfig(
+        model="openai/gpt-4.1-mini",
+        api_key="YOUR_API_KEY",
+    ),
+    system_prompt="You are a careful agent.",
+    enable_fileglide=False,
+    tools=build_fileglide_tools(default_root="D:/Projects/PythonProjects/EasyHarness"),
+)
+```
+
+`build_fileglide_tools(default_root=...)` creates the official scoped toolset. Paths
+that escape the configured root are rejected by FileGlide scope protection.
+
+Each official `fileglide_*` tool also accepts an optional `root` argument for
+that single call. When provided, it overrides the builder's default root
+without additional SDK-level path-range restrictions.
+
+```python
+tools = build_fileglide_tools(default_root="D:/Projects/PythonProjects/EasyHarness")
+tool_map = {tool.tool_name: tool for tool in tools}
+
+result = tool_map["fileglide_read_text"](
+    target="EasyHarness/pyproject.toml",
+    root="D:/Projects/PythonProjects",
+)
+```
+
+## Event Stream
+
+`agent.stream(prompt)` yields a unified `AgentEvent` stream. The public event
+kinds are:
+
+- `thinking`
+- `tool`
+- `assistant`
+- `compress`
+- `system`
+
+Each event uses the same status vocabulary:
+
+- `started`
+- `delta`
+- `completed`
+- `failed`
+
+```python
+for event in agent.stream("Inspect the workspace and explain the next step."):
+    print(event.kind, event.status, event.text)
+```
+
+## Design Boundaries
+
+EasyHarness is intentionally small. v1 does not try to solve:
+
+- UI components
+- Environment-variable orchestration layers
+- Plugin platforms
+- Multi-agent orchestration
+- Root-package re-export sprawl for toolset builders
+
+## Summary
+
+EasyHarness is most useful when you want:
+
+- A minimal `Agent` API
+- Strict tool definitions
+- Streaming runtime visibility
+- A practical, official FileGlide-backed filesystem toolset
+
+If that is your shape of problem, the shortest path is:
+
+1. Create an `Agent`
+2. Define tools with `@tool(...)`
+3. Use the default FileGlide integration or pass a scoped official toolset

easyharness-0.1.0/easyharness/__init__.py

@@ -0,0 +1,18 @@
+"""Minimal public SDK surface for EasyHarness.
+
+The package exposes only five public names: `Agent`, `ModelConfig`,
+`AgentEvent`, `ToolOutput`, and `tool`. Runtime bridging, tool contract
+validation, event mapping, and conversation compression stay inside private
+modules so ordinary callers never have to touch internal objects.
+"""
+
+from ._internal.runtime import Agent
+from ._internal.tools import tool
+from ._internal.types import AgentEvent, ModelConfig, ToolOutput
+
+__all__ = ["Agent", "ModelConfig", "AgentEvent", "ToolOutput", "tool"]
+
+__AUTHOR__ = '吴子豪 / Vortez Wohl'
+__EMAIL__ = 'vortez.wohl@gmail.com'
+__GITHUB__ = 'https://github.com/vortezwohl'
+__BLOG__ = 'https://vortezwohl.github.io'

easyharness-0.1.0/easyharness/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Private implementation package for EasyHarness.
+
+It contains the runtime bridge, tool contracts, event mapping, and
+conversation compression internals. Callers should depend on the stable public
+entry points exposed from top-level `easyharness` instead of these modules.
+"""