runlet 0.1.0__tar.gz

runlet-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report incorrect runtime behavior
+labels: bug
+---
+
+## Summary
+
+Describe the bug.
+
+## Expected Behavior
+
+What should happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Reproduction
+
+Provide the smallest code sample or steps that reproduce the issue.
+
+## Environment
+
+- Python version:
+- Runlet version or commit:
+- Operating system:
+

runlet-0.1.0/.github/ISSUE_TEMPLATE/design_discussion.md

@@ -0,0 +1,18 @@
+---
+name: Design discussion
+about: Discuss runtime architecture, extension points, or tradeoffs
+labels: design
+---
+
+## Topic
+
+What design area should be discussed?
+
+## Context
+
+What constraints or prior decisions matter?
+
+## Options
+
+List the reasonable options and tradeoffs.
+

runlet-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Propose a focused runtime capability
+labels: enhancement
+---
+
+## Problem
+
+What concrete problem should this solve?
+
+## Proposed Shape
+
+Describe the smallest API or behavior that would solve it.
+
+## Scope Check
+
+Does this belong in the runtime core, or should it be an adapter/application
+feature?
+

runlet-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+What changed and why?
+
+## Runtime Impact
+
+Does this affect execution flow, context budgeting, hooks, tools, models, state,
+or events?
+
+## Observability Impact
+
+Does this add, remove, or change emitted events or trace data?
+
+## Verification
+
+What command did you run?
+

runlet-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: PYTHONPATH=src python3 -m unittest discover tests

runlet-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import os
+          import tomllib
+
+          ref = os.environ["GITHUB_REF_NAME"]
+          tag_version = ref.removeprefix("v")
+          data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          package_version = data["project"]["version"]
+          if package_version != tag_version:
+              raise SystemExit(
+                  f"Tag version {tag_version!r} does not match project version {package_version!r}"
+              )
+          PY
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Run tests
+        run: PYTHONPATH=src python -m unittest discover tests
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/runlet
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

runlet-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.venv/
+dist/
+build/
+htmlcov/
+.coverage
+
+# Local planning and design drafts that should not be published.
+.runlet-design/

runlet-0.1.0/AGENTS.md

@@ -0,0 +1,73 @@
+# Repository Instructions
+
+These instructions apply to the entire repository.
+
+## Project Identity
+
+- Project name: Runlet.
+- Python package name: `runlet`.
+- GitHub repository: `https://github.com/DMIAOCHEN/runlet`.
+- License: MIT.
+- Current status: pre-alpha package skeleton.
+
+## Product Direction
+
+Runlet is a lightweight, provider-neutral Python agent runtime library. It is a
+library, not a full application platform.
+
+The core design goals are:
+
+- Keep the runtime small and embeddable.
+- Make context budgeting and compression mandatory before model calls.
+- Provide flexible hooks around model calls, tool calls, state operations, and
+  context compression.
+- Emit structured events for observability.
+- Keep model providers, storage, tracing backends, and application frameworks
+  behind adapters.
+
+## Non-Goals
+
+Do not turn the core package into:
+
+- A web application framework.
+- A hosted agent platform.
+- A worker queue.
+- A UI or trace viewer.
+- A multi-tenant control plane.
+- A graph workflow engine for the first release.
+
+## Design Drafts
+
+Detailed internal design drafts, implementation planning notes, and private
+brainstorming documents must go under:
+
+```text
+.runlet-design/
+```
+
+This directory is intentionally ignored by Git and must not be committed or
+pushed to GitHub.
+
+Public docs under `docs/` should stay high-level and suitable for open-source
+readers. Do not put private planning notes, unfinished internal specs, or
+conversation transcripts in public docs.
+
+## Development Practices
+
+- Prefer simple Python modules and explicit protocols over framework-heavy
+  abstractions.
+- Do not add provider SDK dependencies to core runtime modules.
+- Use `apply_patch` for manual file edits.
+- Keep generated caches such as `__pycache__/` out of commits.
+- Current test command, when tests exist:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover tests
+```
+
+## Git Notes
+
+The default branch is `main`.
+
+If commands need to write Git metadata in this environment, they may require
+escalated permissions because `.git` can appear read-only inside the sandbox.

runlet-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to Runlet will be documented here.
+
+## 0.1.0 - Unreleased
+
+- Initialized the Python package skeleton.
+- Added MIT license metadata.
+- Added early project documentation and GitHub collaboration templates.
+

runlet-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of Conduct
+
+Runlet aims to be a focused and respectful technical project.
+
+Participants are expected to:
+
+- Be direct, constructive, and specific.
+- Debate technical tradeoffs without personal attacks.
+- Respect maintainers' decisions about project scope.
+- Avoid harassment, discrimination, or disruptive behavior.
+
+Unacceptable behavior can be reported through the security or maintainer contact
+channels listed by the project repository. Maintainers may remove comments,
+close issues, or restrict participation when needed to protect the project.
+

runlet-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Runlet is early-stage. Contributions should preserve the project direction:
+small core, explicit extension points, strict context safety, and structured
+observability.
+
+## Development
+
+Use Python 3.10 or newer.
+
+```bash
+python3 -m unittest discover tests
+```
+
+## Contribution Guidelines
+
+- Keep runtime behavior provider-neutral.
+- Prefer protocols and small data objects over framework-heavy abstractions.
+- Do not add application-layer features such as web servers, task queues, UI, or
+  multi-tenant management to the core package.
+- Add tests for runtime behavior once runtime modules exist.
+- Document new extension points before exposing them as public API.
+
+## Pull Requests
+
+Before opening a pull request, include:
+
+- What changed and why.
+- The runtime API or behavior impact.
+- The observability impact, if any.
+- The context-budgeting impact, if any.
+- The test command you ran.
+

runlet-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Runlet contributors
+
+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.
+

runlet-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: runlet
+Version: 0.1.0
+Summary: A tiny observable runtime for Python agents.
+Project-URL: Homepage, https://github.com/DMIAOCHEN/runlet
+Project-URL: Repository, https://github.com/DMIAOCHEN/runlet
+Project-URL: Issues, https://github.com/DMIAOCHEN/runlet/issues
+Author: Runlet contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,hooks,llm,observability,runtime
+Classifier: Development Status :: 2 - Pre-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
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Runlet
+
+Runlet is a tiny observable runtime for Python agents.
+
+The project is a library, not an application framework. Its core direction is a
+provider-neutral, async-first agent runtime with strict context budgeting,
+structured observability, and flexible hooks around model and tool execution.
+
+## Current Status
+
+This repository now contains an MVP runtime skeleton with core contracts,
+events, tools, hooks, context budgeting, streaming, provider adapters, and
+in-memory state. The API is not stable yet.
+
+## Design Goals
+
+- Keep the core runtime small and embeddable.
+- Treat context budgeting and compression as mandatory runtime safety checks.
+- Expose hooks before and after model calls, tool calls, state operations, and
+  context compression.
+- Emit structured events for runs, steps, model calls, tool calls, context
+  changes, state changes, and failures.
+- Stay provider-neutral: model SDKs integrate through adapters, not core
+  dependencies.
+
+## Non-Goals
+
+Runlet core does not aim to provide:
+
+- A web application framework.
+- A hosted agent platform.
+- A task queue or worker system.
+- A UI or trace viewer.
+- A multi-tenant control plane.
+- A graph workflow engine in the first release.
+
+## Project Documents
+
+- [Architecture](docs/architecture.md)
+- [Design Principles](docs/design-principles.md)
+- [Comparison](docs/comparison.md)
+- [Roadmap](docs/roadmap.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+## Minimal Shape
+
+```python
+from runlet import Agent, Runtime, tool
+
+
+@tool
+async def lookup(order_id: str) -> str:
+    return f"order {order_id}"
+
+
+agent = Agent(
+    name="support",
+    instructions="Help users with orders.",
+    model=my_model_provider,
+    tools=(lookup,),
+)
+
+result = await Runtime().run(agent, "Where is order 123?")
+```
+
+## OpenAI Provider
+
+Install the optional OpenAI dependency:
+
+```bash
+pip install "runlet[openai]"
+```
+
+Minimal example:
+
+```python
+from runlet import Agent, Runtime
+from runlet.providers import OpenAIResponsesProvider
+
+
+provider = OpenAIResponsesProvider(model="gpt-5.5")
+
+agent = Agent(
+    name="assistant",
+    instructions="Be helpful.",
+    model=provider,
+)
+
+result = await Runtime().run(agent, "Say hello in one sentence.")
+```
+
+Custom base URL:
+
+```python
+from runlet.providers import OpenAIResponsesProvider
+
+
+provider = OpenAIResponsesProvider(
+    model="gpt-5.5",
+    base_url="https://your-endpoint.example/v1",
+)
+```
+
+Provider-specific request options:
+
+```python
+from runlet.core import Message
+from runlet.core.models import ModelRequest
+from runlet.providers import OpenAIResponsesProvider
+
+
+provider = OpenAIResponsesProvider(model="gpt-5.5")
+
+
+request = ModelRequest(
+    messages=[Message.user("Summarize this briefly.")],
+    options={
+        "openai": {
+            "extra_body": {
+                "reasoning": {"effort": "medium"},
+            },
+        },
+    },
+)
+
+response = await provider.complete(request)
+```
+
+Streaming text deltas:
+
+```python
+from runlet import Agent, Runtime
+from runlet.providers import OpenAIResponsesProvider
+
+
+provider = OpenAIResponsesProvider(model="gpt-5.5")
+agent = Agent(
+    name="assistant",
+    instructions="Be helpful.",
+    model=provider,
+)
+
+async for event in Runtime().stream(agent, "Explain recursion in one sentence."):
+    if event.type == "model.stream.delta":
+        print(event.payload["delta"], end="")
+```
+
+Streaming with tool execution:
+
+```python
+from runlet import Agent, Runtime, tool
+from runlet.providers import OpenAIResponsesProvider
+
+
+@tool
+async def lookup_order(order_id: str) -> str:
+    return f"order {order_id} shipped"
+
+
+provider = OpenAIResponsesProvider(model="gpt-5.5")
+agent = Agent(
+    name="assistant",
+    instructions="Use tools when needed.",
+    model=provider,
+    tools=(lookup_order,),
+)
+
+async for event in Runtime().stream(agent, "Check order 123 and tell me the result."):
+    if event.type == "model.stream.delta":
+        print(event.payload["delta"], end="")
+```
+
+When the provider emits a tool call during streaming, `Runtime.stream()` now
+executes the tool, appends the tool result to the conversation, and continues
+the next model round until the run completes.
+
+Current scope of the provider:
+
+- `complete()` supported
+- `capabilities()` supported
+- `stream()` supported
+- text deltas supported
+- streaming tool execution through `Runtime.stream()` supported
+- `base_url` supported
+- `options["openai"]["extra_body"]` supported
+- provider-specific request options stay under `ModelRequest.options["openai"]`
+
+Current streaming contract:
+
+- providers can emit provider-neutral streaming step events internally
+- `Runtime.stream()` handles multi-round tool execution loops
+- OpenAI is the first provider implementation of this contract
+
+## Development
+
+Run the current test suite:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover tests
+```
+
+## Releasing
+
+Runlet publishes to PyPI from Git tags through GitHub Actions.
+
+Release flow:
+
+1. Update `[project].version` in `pyproject.toml`
+2. Merge the release commit to `main`
+3. Create a version tag such as `v0.1.0`
+4. Push the tag to GitHub
+
+The publish workflow will:
+
+- verify the Git tag matches `pyproject.toml`
+- run the test suite
+- build `sdist` and `wheel`
+- validate package metadata
+- publish to PyPI through Trusted Publishing
+
+Example:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Repository setup requirement:
+
+- configure PyPI Trusted Publishing for this GitHub repository and the
+  `.github/workflows/publish.yml` workflow