lite-agent-sdk 0.1.0__tar.gz

lite_agent_sdk-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Zander073

lite_agent_sdk-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## Summary
+
+What changed and why.
+
+## Test plan
+
+How you checked it.

lite_agent_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

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

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+
+      - name: Build
+        run: uv build

lite_agent_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Check tag and changelog
+        run: |
+          uv run python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          with open("pyproject.toml", "rb") as handle:
+              version = tomllib.load(handle)["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if tag != version:
+              raise SystemExit(f"tag {tag} does not match pyproject version {version}")
+          text = Path("CHANGELOG.md").read_text()
+          pattern = rf"^## {re.escape(version)}(?: [^\n]+)?\n(.*?)(?=^## |\Z)"
+          match = re.search(pattern, text, flags=re.M | re.S)
+          if match is None:
+              raise SystemExit(f"CHANGELOG.md has no section for {version}")
+          Path("release-notes.md").write_text(match.group(1).strip() + "\n")
+          PY
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always
+
+      - name: Install from PyPI
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          for _ in $(seq 1 12); do
+            rm -rf /tmp/smoke
+            if uv venv --python 3.13 /tmp/smoke \
+              && uv pip install --python /tmp/smoke/bin/python \
+                --index-url https://pypi.org/simple \
+                "lite-agent-sdk==${version}" \
+              && /tmp/smoke/bin/python -c \
+                "import importlib.metadata as meta; assert meta.version('lite-agent-sdk') == '${version}'"; then
+              exit 0
+            fi
+            sleep 10
+          done
+          echo "lite-agent-sdk==${version} was not installable from PyPI"
+          exit 1
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md

lite_agent_sdk-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# temp implementation plan
+open_items_to_address.md
+
+# live api test script with pasted keys
+scripts/live_test.py

lite_agent_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

lite_agent_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md
+
+Conventions for working in this repo. Applies to humans and any AI
+coding agent making changes here.
+
+## Implementation
+
+- Target API: `docs/lite_agent_sdk_tdd.md`. Follow the TDD when implementing.
+
+## Releases
+
+- Version, changelog, and publish steps live in `docs/releasing.md`.
+- Do not tag or publish unless that protocol says to.
+
+## Project layout
+
+- `src/lite_agent_sdk/` - the package. Import name is `lite_agent_sdk`
+  (underscore); the PyPI distribution name is `lite-agent-sdk` (hyphen).
+  These are allowed to differ and both are intentional.
+- `src/` layout on purpose: it prevents tests or local scripts from
+  silently importing the source tree directly. Every test run goes
+  through the actual installed package, the same way a real consumer of
+  the library would get it.
+- `tests/` and `docs/` at the repo root, alongside `src/`.
+
+## Environment
+
+- Python 3.13+.
+- `uv` for dependency and environment management. Use `uv add`, `uv
+  sync`, `uv run`. No bare `pip`, no manually edited lockfiles.
+- `ruff` (config in `ruff.toml`) for linting and formatting.
+- `ty` for type checking.
+- Both must pass before a change is considered done. Run
+  `uv run ruff check .` and `uv run ty check .`.
+
+## Code style
+
+- Prefer clear, self-explanatory code over comments. If a rename or a
+  restructure would make a comment unnecessary, do that instead of
+  writing the comment.
+- Comments are lowercase only, including the first word.
+- Only write a comment when the code's behavior isn't obvious from
+  reading it, or when it encodes something implicit - a provider-specific
+  workaround, an assumption about input shape, why an edge case is
+  handled a particular way. Do not restate what the code already says.
+- Docstrings are rare. Reserve them for genuinely complex logic where a
+  reader benefits from a summary before diving into the body. A simple
+  function with a clear name and clear arguments does not need one.
+- Absolute imports only. No relative imports (`from .foo import bar`),
+  even within `lite_agent_sdk/`. Enforced by ruff (`TID` rules).
+- No emojis, no em dashes, no filler phrases in comments, docstrings, or
+  commit messages.
+
+## Errors
+
+- Provider/API errors (auth, rate limits, network, malformed responses)
+  bubble up unmodified. Never catch and re-wrap them in a custom
+  exception type.
+- Tool execution errors are the one exception: caught inside the agent's
+  resolve step, turned into a tool result the model can see and react
+  to. This is a deliberate asymmetry, not an inconsistency.
+- `AgentError` is for programmer-level failures (`unknown_provider`,
+  `missing_api_key`, `unknown_tool`, `invalid_output`). It is not used
+  for provider errors or tool failures.
+- Human approval is not an error. It lives on `ToolCall.approval`
+  (`pending`, `approved`, `denied`) and ends the invocation with
+  `finish_reason="waiting_approval"`. Never model it as an exception.
+
+## Tests
+
+- All tests live under `tests/`, split into:
+  - `tests/unit/` - no network calls, no real credentials. Agent tests
+    use `FakeAdapter` in `tests/unit/fake_adapter.py`, injected with
+    `Agent(..., adapter=...)`. Fast, run on every change.
+  - `tests/integration/` - exercises real adapter translation logic
+    against recorded, provider-shaped HTTP responses using `vcrpy` (via
+    `pytest-recording`, `@pytest.mark.vcr`). No live API key is required
+    to run these, in CI or locally. Cassettes live in
+    `tests/integration/cassettes/` and are committed.
+- New behavior gets a unit test. New provider-specific translation logic
+  gets an integration test against a cassette - a hand-written mock is
+  exactly what would hide a translation bug.
+- Cassettes are recorded once, manually, by whoever changes
+  provider-specific translation logic, using a real key locally.
+  `filter_headers` in the VCR config strips the API key from recorded
+  request headers before a cassette is committed. Check the diff of any
+  new or re-recorded cassette - an unscrubbed cassette is a leaked
+  credential in git history.
+- Re-recording a cassette is a deliberate, occasional action, not
+  something CI does automatically.
+
+## AI writing guidelines
+
+Applies to everything in `docs/`, the README, comments, and commit
+messages.
+
+### Tone and language
+
+- Use Simplified Technical English (STE) with a light, human touch.
+  Avoid sounding robotic.
+- Write clearly, simply, and coherently. Prefer short, direct sentences.
+- Be especially clear when explaining concepts, steps, or trade-offs.
+- Say the thing once, clearly, and stop. If a sentence does not add
+  information, cut it.
+
+### Banned patterns
+
+- No emojis.
+- No em dashes. Use a single hyphen ("-") instead.
+- No horizontal rules or page separators (`---`) in markdown.
+- No filler such as "in today's fast-paced world".
+
+### Structure
+
+- Organize content with headers.
+- Use bullet points and numbered lists where they help.
+- Keep paragraphs to five sentences or fewer.
+- Avoid walls of text. Break up long explanations with code, lists, or
+  diagrams.
+
+### Code and diagrams
+
+- Include code examples when they help. Pseudocode is fine.
+- Prefer Python when using a real language.
+- Prefer short examples over long explanations.
+- Use Mermaid diagrams for flows, architecture, and relationships.
+- For complex documentation, favor code and diagrams over extra prose.
+
+### Math
+
+- Use LaTeX for equations and mathematical expressions.

lite_agent_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-11-04
+
+### Added
+
+- Async `Agent.run` and `Agent.stream` for one turn at a time.
+- OpenAI and Anthropic adapters.
+- Tools, with approval that pauses on `waiting_approval`.
+- Structured output through `output_schema`.
+- Usage events for each model hop.

lite_agent_sdk-0.1.0/LICENSE

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

lite_agent_sdk-0.1.0/Makefile

@@ -0,0 +1,19 @@
+.PHONY: help lint format test
+
+.DEFAULT_GOAL := help
+
+help:
+	@echo "lint    run ruff check, ruff format --check, and ty"
+	@echo "format  apply ruff formatting"
+	@echo "test    run the pytest suite"
+
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+	uv run ty check .
+
+format:
+	uv run ruff format .
+
+test:
+	uv run pytest

lite_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: lite-agent-sdk
+Version: 0.1.0
+Summary: Minimal, lightweight, provider-agnostic LLM agent SDK
+Project-URL: Repository, https://github.com/Zander073/lite-agent-sdk
+Project-URL: Changelog, https://github.com/Zander073/lite-agent-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Zander073/lite-agent-sdk/blob/main/docs/usage.md
+Author: Zander Zemliak
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: anthropic<3,>=2.5.0
+Requires-Dist: openai<4,>=3.46.0
+Requires-Dist: pydantic<3,>=2.13.4
+Description-Content-Type: text/markdown
+
+# lite-agent-sdk
+
+A small, async, provider-agnostic agent SDK for Python. It runs one agent turn at a time. You own the transcript.
+
+## Install
+
+```bash
+uv add lite-agent-sdk
+```
+
+The OpenAI and Anthropic SDKs are installed with the package.
+
+## API keys
+
+Pass `api_key=` to `Agent`, or set the provider environment variable:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Quick start
+
+```python
+import asyncio
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from lite_agent_sdk import Agent, Message
+
+
+async def main() -> None:
+    agent = Agent(
+        model="anthropic/claude-haiku-4-5-20251001",
+        system_prompt="Be brief.",
+    )
+    messages = [
+        Message(id=str(uuid4()), role="user", content="Hello", created_at=datetime.now(UTC)),
+    ]
+    result = await agent.run(messages)
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+`model` is `provider/model-id`. Supported providers are `openai` and `anthropic`.
+
+## Docs
+
+- [Usage](docs/usage.md): agents, transcripts, tools, approval, streaming, and errors.
+- [Structured output](docs/structured-output.md): `output_schema` and provider notes.
+- [Technical design](docs/lite_agent_sdk_tdd.md): the target API and design decisions.
+- [Changelog](CHANGELOG.md): published versions.
+
+## Development
+
+```bash
+uv sync
+make lint
+make format
+make test
+```
+
+Releases follow [docs/releasing.md](docs/releasing.md). Python 3.13 or newer is required.

lite_agent_sdk-0.1.0/README.md

@@ -0,0 +1,65 @@
+# lite-agent-sdk
+
+A small, async, provider-agnostic agent SDK for Python. It runs one agent turn at a time. You own the transcript.
+
+## Install
+
+```bash
+uv add lite-agent-sdk
+```
+
+The OpenAI and Anthropic SDKs are installed with the package.
+
+## API keys
+
+Pass `api_key=` to `Agent`, or set the provider environment variable:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Quick start
+
+```python
+import asyncio
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from lite_agent_sdk import Agent, Message
+
+
+async def main() -> None:
+    agent = Agent(
+        model="anthropic/claude-haiku-4-5-20251001",
+        system_prompt="Be brief.",
+    )
+    messages = [
+        Message(id=str(uuid4()), role="user", content="Hello", created_at=datetime.now(UTC)),
+    ]
+    result = await agent.run(messages)
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+`model` is `provider/model-id`. Supported providers are `openai` and `anthropic`.
+
+## Docs
+
+- [Usage](docs/usage.md): agents, transcripts, tools, approval, streaming, and errors.
+- [Structured output](docs/structured-output.md): `output_schema` and provider notes.
+- [Technical design](docs/lite_agent_sdk_tdd.md): the target API and design decisions.
+- [Changelog](CHANGELOG.md): published versions.
+
+## Development
+
+```bash
+uv sync
+make lint
+make format
+make test
+```
+
+Releases follow [docs/releasing.md](docs/releasing.md). Python 3.13 or newer is required.