Metadata-Version: 2.4
Name: runlet-harness
Version: 0.1.0a1
Summary: Application integration helpers for Runlet.
Project-URL: Homepage, https://github.com/DMIAOCHEN/runlet-harness
Project-URL: Repository, https://github.com/DMIAOCHEN/runlet-harness
Project-URL: Issues, https://github.com/DMIAOCHEN/runlet-harness/issues
Author: Runlet Harness contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent,langfuse,observability,runlet,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: runlet>=0.2.0b3
Provides-Extra: dev
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: langfuse
Requires-Dist: langfuse<5,>=4.7; extra == 'langfuse'
Description-Content-Type: text/markdown

# Runlet Harness

[![PyPI version](https://img.shields.io/pypi/v/runlet-harness.svg)](https://pypi.org/project/runlet-harness/)
[![Python versions](https://img.shields.io/pypi/pyversions/runlet-harness.svg)](https://pypi.org/project/runlet-harness/)
[![CI](https://github.com/DMIAOCHEN/runlet-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/DMIAOCHEN/runlet-harness/actions/workflows/ci.yml)

Application integration helpers for [Runlet](https://github.com/DMIAOCHEN/runlet).

`runlet-harness` keeps third-party adapters, environment-based configuration,
and background delivery concerns outside the small Runlet runtime core.

## Install

Base package:

```bash
pip install runlet-harness
```

With Langfuse support:

```bash
pip install "runlet-harness[langfuse]"
```

## Langfuse

Cloud configuration:

```dotenv
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
```

Self-hosted configuration:

```dotenv
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://langfuse.example.com
```

Usage:

```python
from runlet import CompositeEventSink, InMemoryObserver, Runtime
from runlet_harness.observability import LangfuseEventSink

observer = InMemoryObserver()
langfuse = LangfuseEventSink.from_env()

sinks = [observer]
if langfuse is not None:
    sinks.append(langfuse)

runtime = Runtime(event_sink=CompositeEventSink(sinks))

try:
    result = await runtime.run(agent, "hello")
finally:
    if langfuse is not None:
        await langfuse.shutdown()
```

By default, the Langfuse sink records metadata, status, timing, tool names, and
final outputs. It does not record inputs, reasoning, streaming deltas, tool
arguments, tool results, or human-submitted values unless explicitly configured.
## Development

Run the test suite:

```bash
PYTHONPATH=src python -m unittest discover tests
```

Run type checking after installing development dependencies:

```bash
pyright
```

## Release

Runlet Harness publishes to PyPI from Git tags through GitHub Actions.

Typical release flow:

1. Update the version in `pyproject.toml`.
2. Merge to `main`.
3. Create a tag such as `v0.1.0a1`.
4. Push the tag.

```bash
git tag v0.1.0a1
git push origin v0.1.0a1
```