deepharness 0.1.0__tar.gz

deepharness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sayed Shaun
+
+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.

deepharness-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: deepharness
+Version: 0.1.0
+Summary: Compose LLM agents into typed, concurrent workflows.
+Author-email: Sayed Shaun <sayedshaun4@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sayedshaun/deepharness
+Project-URL: Documentation, https://sayedshaun.github.io/deepharness/
+Project-URL: Repository, https://github.com/sayedshaun/deepharness
+Project-URL: Issues, https://github.com/sayedshaun/deepharness/issues
+Keywords: agents,llm,workflow,graph,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="docs/assets/logo.svg" width="160" alt="DeepHarness logo">
+
+# DeepHarness
+
+**Compose LLM agents into typed, concurrent workflows.**
+
+A lightweight framework for wiring plain Python functions — and the agents inside them — into a
+graph that runs branches in parallel, routes on conditions, and threads one typed state
+object through the whole thing.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![Dependencies: httpx only](https://img.shields.io/badge/dependencies-httpx%20only-6E63F5)](pyproject.toml) [![Async native](https://img.shields.io/badge/async-native-0EA5E9)](#quickstart) [![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://github.com/astral-sh/ruff) [![Read the docs](https://img.shields.io/badge/docs-read%20the%20docs-3776AB?logo=materialformkdocs&logoColor=white)](https://sayedshaun.github.io/deepharness/)
+
+</div>
+
+---
+
+## Why DeepHarness
+
+- **One dependency. That's it.** `httpx`. Providers talk to vendor REST APIs
+  directly — no vendor SDKs, no transitive dependency sprawl.
+- **Your state is a dataclass.** Not an untyped dict. Your editor autocompletes it, your type
+  checker checks it.
+- **Nodes are just functions.** Sync or async, decorated in place. No base class to inherit,
+  no runner object to construct.
+- **Parallel by default.** Independent branches run concurrently via `asyncio`; sync functions
+  are offloaded to threads so a blocking call never stalls the event loop.
+- **One provider interface, a dozen vendors.** `OpenAI`, `Anthropic`, `Gemini`, and OpenAI-compatible
+  gateways (`Groq`, `Together`, `Fireworks`, `DeepSeek`, `Mistral`, `Cerebras`, `OpenRouter`, `XAI`,
+  `Ollama`, `LMStudio`, `VLLM`) all share the same `LLM` interface.
+
+## Install
+
+```bash
+pip install deepharness
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/sayedshaun/deepharness.git
+```
+
+## Quickstart
+
+An `Agent` runs a think/act loop against a model: ask for a response, dispatch any tool calls
+it requests, repeat until the model answers with no tool calls.
+
+```python
+from deepharness import Agent, Message, OpenAI, tool
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Look up the current weather for a city."""
+    return f"It is 22°C and sunny in {city}."
+
+
+agent = Agent(
+    OpenAI(model="gpt-4o-mini", api_key="sk-..."),
+    tools=[get_weather],
+)
+
+result = await agent.arun("Weather in Oslo?")
+print(result.output)
+```
+
+An `Agent` can itself be handed to another agent as a tool via `as_tool()`, so one agent can
+delegate a task to another:
+
+```python
+researcher = Agent(OpenAI(model="gpt-4o-mini", api_key="sk-..."), name="researcher")
+
+editor = Agent(
+    OpenAI(model="gpt-4o-mini", api_key="sk-..."),
+    name="editor",
+    tools=[researcher.as_tool(description="Look up facts on a topic.")],
+)
+```
+
+## Graphs
+
+For fixed, known-shape workflows — run these steps, some in parallel, then merge — wire plain
+functions (or agents) into a `Graph` instead:
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from deepharness import Graph
+
+
+@dataclass
+class State:
+    sales: str = ""
+    churn: str = ""
+    summary: str = ""
+
+
+graph = Graph(State)
+
+
+@graph.add(start=True)
+async def fetch_sales(state: State) -> State:
+    await asyncio.sleep(0.5)
+    state.sales = "Sales up 12% QoQ."
+    return state
+
+
+@graph.add(start=True)
+async def fetch_churn(state: State) -> State:
+    await asyncio.sleep(0.3)
+    state.churn = "Churn down to 4%."
+    return state
+
+
+@graph.add(end=True)
+def summarize(state: State) -> State:
+    state.summary = f"{state.sales} {state.churn}"
+    return state
+
+
+graph.connect(fetch_sales, summarize)
+graph.connect(fetch_churn, summarize)
+
+executor = graph.build()
+result = asyncio.run(executor.run(State()))
+
+print(result.summary)  # Sales up 12% QoQ. Churn down to 4%.
+```
+
+`fetch_sales` and `fetch_churn` both run in the first wave, concurrently. `summarize` waits
+for both before running.
+
+**Agent or Graph?** Reach for `as_tool()` when an LLM should decide at runtime whether and
+which sub-agent to call. Reach for `Graph` when the workflow's shape — which steps, which run
+in parallel, in what order — is known ahead of time.
+
+See the **[full documentation](https://sayedshaun.github.io/deepharness/)** for graphs, agents,
+tools, providers, and the API reference.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff format . && ruff check .
+```
+
+Docs are built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/):
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+---
+
+<div align="center">
+<sub>Simple, modular, typed, dependency-light.</sub>
+</div>

deepharness-0.1.0/README.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+<img src="docs/assets/logo.svg" width="160" alt="DeepHarness logo">
+
+# DeepHarness
+
+**Compose LLM agents into typed, concurrent workflows.**
+
+A lightweight framework for wiring plain Python functions — and the agents inside them — into a
+graph that runs branches in parallel, routes on conditions, and threads one typed state
+object through the whole thing.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![Dependencies: httpx only](https://img.shields.io/badge/dependencies-httpx%20only-6E63F5)](pyproject.toml) [![Async native](https://img.shields.io/badge/async-native-0EA5E9)](#quickstart) [![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://github.com/astral-sh/ruff) [![Read the docs](https://img.shields.io/badge/docs-read%20the%20docs-3776AB?logo=materialformkdocs&logoColor=white)](https://sayedshaun.github.io/deepharness/)
+
+</div>
+
+---
+
+## Why DeepHarness
+
+- **One dependency. That's it.** `httpx`. Providers talk to vendor REST APIs
+  directly — no vendor SDKs, no transitive dependency sprawl.
+- **Your state is a dataclass.** Not an untyped dict. Your editor autocompletes it, your type
+  checker checks it.
+- **Nodes are just functions.** Sync or async, decorated in place. No base class to inherit,
+  no runner object to construct.
+- **Parallel by default.** Independent branches run concurrently via `asyncio`; sync functions
+  are offloaded to threads so a blocking call never stalls the event loop.
+- **One provider interface, a dozen vendors.** `OpenAI`, `Anthropic`, `Gemini`, and OpenAI-compatible
+  gateways (`Groq`, `Together`, `Fireworks`, `DeepSeek`, `Mistral`, `Cerebras`, `OpenRouter`, `XAI`,
+  `Ollama`, `LMStudio`, `VLLM`) all share the same `LLM` interface.
+
+## Install
+
+```bash
+pip install deepharness
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/sayedshaun/deepharness.git
+```
+
+## Quickstart
+
+An `Agent` runs a think/act loop against a model: ask for a response, dispatch any tool calls
+it requests, repeat until the model answers with no tool calls.
+
+```python
+from deepharness import Agent, Message, OpenAI, tool
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Look up the current weather for a city."""
+    return f"It is 22°C and sunny in {city}."
+
+
+agent = Agent(
+    OpenAI(model="gpt-4o-mini", api_key="sk-..."),
+    tools=[get_weather],
+)
+
+result = await agent.arun("Weather in Oslo?")
+print(result.output)
+```
+
+An `Agent` can itself be handed to another agent as a tool via `as_tool()`, so one agent can
+delegate a task to another:
+
+```python
+researcher = Agent(OpenAI(model="gpt-4o-mini", api_key="sk-..."), name="researcher")
+
+editor = Agent(
+    OpenAI(model="gpt-4o-mini", api_key="sk-..."),
+    name="editor",
+    tools=[researcher.as_tool(description="Look up facts on a topic.")],
+)
+```
+
+## Graphs
+
+For fixed, known-shape workflows — run these steps, some in parallel, then merge — wire plain
+functions (or agents) into a `Graph` instead:
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from deepharness import Graph
+
+
+@dataclass
+class State:
+    sales: str = ""
+    churn: str = ""
+    summary: str = ""
+
+
+graph = Graph(State)
+
+
+@graph.add(start=True)
+async def fetch_sales(state: State) -> State:
+    await asyncio.sleep(0.5)
+    state.sales = "Sales up 12% QoQ."
+    return state
+
+
+@graph.add(start=True)
+async def fetch_churn(state: State) -> State:
+    await asyncio.sleep(0.3)
+    state.churn = "Churn down to 4%."
+    return state
+
+
+@graph.add(end=True)
+def summarize(state: State) -> State:
+    state.summary = f"{state.sales} {state.churn}"
+    return state
+
+
+graph.connect(fetch_sales, summarize)
+graph.connect(fetch_churn, summarize)
+
+executor = graph.build()
+result = asyncio.run(executor.run(State()))
+
+print(result.summary)  # Sales up 12% QoQ. Churn down to 4%.
+```
+
+`fetch_sales` and `fetch_churn` both run in the first wave, concurrently. `summarize` waits
+for both before running.
+
+**Agent or Graph?** Reach for `as_tool()` when an LLM should decide at runtime whether and
+which sub-agent to call. Reach for `Graph` when the workflow's shape — which steps, which run
+in parallel, in what order — is known ahead of time.
+
+See the **[full documentation](https://sayedshaun.github.io/deepharness/)** for graphs, agents,
+tools, providers, and the API reference.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff format . && ruff check .
+```
+
+Docs are built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/):
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+---
+
+<div align="center">
+<sub>Simple, modular, typed, dependency-light.</sub>
+</div>

deepharness-0.1.0/deepharness/__init__.py

@@ -0,0 +1,101 @@
+from deepharness.agent import (
+    FINAL_TOOL,
+    Agent,
+    AgentState,
+    Budget,
+    Ctx,
+    Finished,
+    Message,
+    PendingHumanInput,
+    StopReason,
+    TokenBudgetExceeded,
+    Toolbox,
+    ToolSpec,
+    load_session,
+    save_session,
+    tool,
+)
+from deepharness.errors import (
+    ConfigurationError,
+    DeepHarnessError,
+    HumanInputRequired,
+    ProviderError,
+    ToolNotFoundError,
+)
+from deepharness.graph import (
+    ConcurrentUpdateError,
+    ExecutionError,
+    Executor,
+    Graph,
+    NodeSpec,
+    StepLimitExceeded,
+    concat,
+    merge_dicts,
+)
+from deepharness.providers import (
+    VLLM,
+    XAI,
+    Anthropic,
+    Cerebras,
+    Completed,
+    DeepSeek,
+    Fireworks,
+    Gemini,
+    Groq,
+    LMStudio,
+    Mistral,
+    Ollama,
+    OpenAI,
+    OpenRouter,
+    TextDelta,
+    Together,
+    TokenUsage,
+)
+
+__all__ = [
+    "FINAL_TOOL",
+    "VLLM",
+    "XAI",
+    "Agent",
+    "AgentState",
+    "Anthropic",
+    "Budget",
+    "Cerebras",
+    "Completed",
+    "ConcurrentUpdateError",
+    "ConfigurationError",
+    "Ctx",
+    "DeepHarnessError",
+    "DeepSeek",
+    "ExecutionError",
+    "Executor",
+    "Finished",
+    "Fireworks",
+    "Gemini",
+    "Graph",
+    "Groq",
+    "HumanInputRequired",
+    "LMStudio",
+    "Message",
+    "Mistral",
+    "NodeSpec",
+    "Ollama",
+    "OpenAI",
+    "OpenRouter",
+    "PendingHumanInput",
+    "ProviderError",
+    "StepLimitExceeded",
+    "StopReason",
+    "TextDelta",
+    "Together",
+    "TokenBudgetExceeded",
+    "TokenUsage",
+    "ToolNotFoundError",
+    "ToolSpec",
+    "Toolbox",
+    "concat",
+    "load_session",
+    "merge_dicts",
+    "save_session",
+    "tool",
+]

deepharness-0.1.0/deepharness/agent/__init__.py

@@ -0,0 +1,33 @@
+from ..tools.toolbox import Ctx, Toolbox, ToolSpec, tool
+from .loop import Agent, TokenBudgetExceeded
+from .output import FINAL_TOOL
+from .state import (
+    AgentState,
+    Budget,
+    Finished,
+    Message,
+    PendingHumanInput,
+    StopReason,
+    as_dict,
+    load_session,
+    save_session,
+)
+
+__all__ = [
+    "FINAL_TOOL",
+    "Agent",
+    "AgentState",
+    "Budget",
+    "Ctx",
+    "Finished",
+    "Message",
+    "PendingHumanInput",
+    "StopReason",
+    "TokenBudgetExceeded",
+    "ToolSpec",
+    "Toolbox",
+    "as_dict",
+    "load_session",
+    "save_session",
+    "tool",
+]