langgraph-events 0.2.0__tar.gz

langgraph_events-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: check src/ tests/
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest tests/

langgraph_events-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group docs --frozen
+      - run: uv run mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

langgraph_events-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  build:
+    name: Build and validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(grep '^version' pyproject.toml | head -1 | cut -d'"' -f2)
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag v$TAG does not match pyproject.toml version $PKG"
+            exit 1
+          fi
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/
+      - run: uv run pytest tests/
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: uv publish --trusted-publishing always

langgraph_events-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.venv/
+.coverage
+.claude/
+.worktrees/
+site/

langgraph_events-0.2.0/.pdm-python

@@ -0,0 +1 @@
+/Users/paulsoares/Development/langgraph-events/.venv/bin/python

langgraph_events-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+default_language_version:
+  python: python3.11
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: validate-tests
+        name: validate tests
+        entry: bash -c "uv run python scripts/validate_tests.py"
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: mypy
+        name: mypy
+        language: system
+        entry: uv run mypy src/
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+
+      - id: jscpd
+        name: jscpd
+        language: system
+        entry: npx jscpd src/ tests/ --min-tokens 30 --min-lines 2 --threshold 5
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+        files: ^(src/|tests/)
+
+      - id: mermaid-graphs
+        name: mermaid-graphs
+        language: system
+        entry: uv run python scripts/generate_mermaid.py
+        pass_filenames: false
+        require_serial: true
+        files: ^examples/.*\.py$
+
+      - id: pytest
+        name: pytest
+        language: system
+        entry: bash -c 'uv run coverage run -m pytest && uv run coverage report'
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+        files: ^(src/|tests/)

langgraph_events-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

langgraph_events-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-06
+
+### Added
+- Field-level dispatch for `@on` decorator
+- AG-UI protocol adapter with `langgraph-events[agui]` optional dependency
+- Custom event emit helpers (`emit_custom`, `aemit_custom`, `emit_state_snapshot`, `aemit_state_snapshot`)
+- First-class `StateSnapshotFrame` for state snapshot streaming
+- `SKIP` sentinel for scalar reducer no-op returns
+- Graceful `Halted` subtypes (`MaxRoundsExceeded`, `Cancelled`) and `OrphanedEventWarning`
+- LLM token streaming (`LLMToken`, `LLMStreamEnd` frames)
+- MkDocs documentation site on GitHub Pages
+
+### Changed
+- Restructured docs for better DX (split concepts, grouped API reference)
+- `Interrupted` is now a bare marker class — subclass with typed fields
+
+### Fixed
+- AG-UI adapter message deduplication and ID reconciliation
+- `connect()` yielding no events for new threads
+- Resume interrupt detection for interrupts created during resume
+
+## [0.1.0] - 2026-02-20
+
+### Added
+- Core `Event`, `EventGraph`, and `@on` decorator
+- `Reducer` and `ScalarReducer` for custom state channels
+- `EventLog` with query methods (`first`, `count`, `after`, `before`, `select`)
+- Multi-subscription `@on(A, B)` and `Scatter` for fan-out
+- `Auditable` and `MessageEvent` base events
+- `SystemPromptSet` event for system prompts
+- Config and store injection for handlers
+- `Interrupted` / `Resumed` events for human-in-the-loop
+- Mermaid diagram generation
+- BDD-style test suite with pytest-describe
+- CI workflow (lint, typecheck, test)
+
+[Unreleased]: https://github.com/cadance-io/langgraph-events/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/cadance-io/langgraph-events/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/cadance-io/langgraph-events/releases/tag/v0.1.0

langgraph_events-0.2.0/CLAUDE.md

@@ -0,0 +1,24 @@
+# langgraph-events
+
+Event-driven abstraction for LangGraph. State IS events.
+
+## Commands
+
+- **Tests:** `uv run pytest tests/`
+- **Lint:** `uv run ruff check src/ tests/`
+- **Format:** `uv run ruff format src/ tests/`
+- **Type check:** `uv run mypy src/`
+
+## Structure
+
+- `src/langgraph_events/` — library source
+- `tests/` — BDD-style with pytest-describe (`describe_`/`when_`/`it_`)
+- `examples/` — usage examples
+
+## Conventions
+
+- Python 3.10+, line length 88
+- Use `uv` to run all tooling (not bare `python` or `pytest`)
+- Ruff for linting and formatting (config in pyproject.toml)
+- mypy strict mode
+- Tests: `describe_` groups by API surface, `when_` mirrors code branches, `it_` names the assertion. Test each behavior once at the API boundary where it's consumed. Shared event classes in `conftest.py`; scenario-specific events inline. Event classes used as handler type annotations must be defined at module level (not inside `describe_`/`when_` blocks) so Python can resolve forward references at runtime.

langgraph_events-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest tests/
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run mypy src/
+```
+
+## Releasing
+
+### One-time setup
+
+Before the first release, the repo owner must:
+
+1. **Register trusted publishers on PyPI** — go to [pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/) and add a pending trusted publisher:
+   - Project name: `langgraph-events`
+   - Owner: `cadance-io`
+   - Repository: `langgraph-events`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+
+2. **Create GitHub environment** — go to repo Settings → Environments and create `pypi`
+
+### Cutting a release
+
+1. Make sure `CHANGELOG.md` has entries under `[Unreleased]`.
+
+2. Run the release script:
+
+   ```bash
+   # Preview changes
+   uv run python scripts/release.py minor --dry-run
+
+   # Cut the release (bumps version, stamps changelog, commits, tags)
+   uv run python scripts/release.py minor
+   ```
+
+   The script accepts `major`, `minor`, `patch`, or an explicit version like `1.0.0`.
+
+3. Push to trigger the publish workflow:
+
+   ```bash
+   git push origin main v0.3.0
+   ```
+
+   The workflow builds the package and publishes to PyPI.
+
+### What the release script does
+
+`scripts/release.py` automates:
+
+- Bumps version in `pyproject.toml`, `README.md`, `docs/index.md`
+- Stamps `[Unreleased]` in `CHANGELOG.md` with the new version and today's date
+- Updates changelog footer comparison links
+- Runs `uv lock` to sync `uv.lock`
+- Commits with message `release: vX.Y.Z`
+- Creates git tag `vX.Y.Z`
+
+Preflight checks ensure you're on `main`, working tree is clean, `[Unreleased]` has content, and the tag doesn't already exist.
+
+### Changelog
+
+We use [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. Add entries under `[Unreleased]` as you work — the release script moves them to the new version section automatically.

langgraph_events-0.2.0/LICENSE

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

langgraph_events-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: langgraph-events
+Version: 0.2.0
+Summary: Opinionated event-driven abstraction for LangGraph. State IS events.
+Project-URL: Homepage, https://cadance-io.github.io/langgraph-events/
+Project-URL: Repository, https://github.com/cadance-io/langgraph-events
+Project-URL: Documentation, https://cadance-io.github.io/langgraph-events/
+Project-URL: Changelog, https://github.com/cadance-io/langgraph-events/blob/main/CHANGELOG.md
+Author: cadance-io
+License-Expression: MIT
+License-File: LICENSE
+Keywords: event-driven,events,langgraph,state-machine
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langgraph>=0.2.0
+Provides-Extra: agui
+Requires-Dist: ag-ui-protocol>=0.1.0; extra == 'agui'
+Description-Content-Type: text/markdown
+
+# langgraph-events
+
+Opinionated event-driven abstraction for LangGraph. **State IS events.**
+
+> [!CAUTION]
+> **Experimental (v0.2.0)** - This is an early-stage personal project, not a supported product. The API will change without notice or migration path.
+
+## Quick Start
+
+```python
+from langgraph_events import Event, EventGraph, on
+
+
+class MessageReceived(Event):
+    text: str
+
+
+class ReplyProduced(Event):
+    text: str
+
+
+@on(MessageReceived)
+def reply(event: MessageReceived) -> ReplyProduced:
+    return ReplyProduced(text=f"Echo: {event.text}")
+
+
+graph = EventGraph([reply])
+log = graph.invoke(MessageReceived(text="hello"))
+print(log.latest(ReplyProduced))
+```
+
+## Installation
+
+```bash
+pip install langgraph-events
+
+# With AG-UI adapter support
+pip install "langgraph-events[agui]"
+
+# From source (development)
+pip install git+https://github.com/cadance-io/langgraph-events.git
+```
+
+## Documentation
+
+- Docs site (GitHub Pages): <https://cadance-io.github.io/langgraph-events/>
+- Local docs index: [`docs/index.md`](docs/index.md)
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- Core concepts: [`docs/concepts.md`](docs/concepts.md)
+- Patterns: [`docs/patterns.md`](docs/patterns.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- AG-UI adapter: [`docs/agui.md`](docs/agui.md)
+- Checkpointer and graph evolution: [`docs/checkpointer-evolution.md`](docs/checkpointer-evolution.md)
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest tests/
+uv run ruff check src/ tests/
+uv run mypy src/
+```
+
+## License
+
+MIT - see [`LICENSE`](LICENSE).

langgraph_events-0.2.0/README.md

@@ -0,0 +1,66 @@
+# langgraph-events
+
+Opinionated event-driven abstraction for LangGraph. **State IS events.**
+
+> [!CAUTION]
+> **Experimental (v0.2.0)** - This is an early-stage personal project, not a supported product. The API will change without notice or migration path.
+
+## Quick Start
+
+```python
+from langgraph_events import Event, EventGraph, on
+
+
+class MessageReceived(Event):
+    text: str
+
+
+class ReplyProduced(Event):
+    text: str
+
+
+@on(MessageReceived)
+def reply(event: MessageReceived) -> ReplyProduced:
+    return ReplyProduced(text=f"Echo: {event.text}")
+
+
+graph = EventGraph([reply])
+log = graph.invoke(MessageReceived(text="hello"))
+print(log.latest(ReplyProduced))
+```
+
+## Installation
+
+```bash
+pip install langgraph-events
+
+# With AG-UI adapter support
+pip install "langgraph-events[agui]"
+
+# From source (development)
+pip install git+https://github.com/cadance-io/langgraph-events.git
+```
+
+## Documentation
+
+- Docs site (GitHub Pages): <https://cadance-io.github.io/langgraph-events/>
+- Local docs index: [`docs/index.md`](docs/index.md)
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- Core concepts: [`docs/concepts.md`](docs/concepts.md)
+- Patterns: [`docs/patterns.md`](docs/patterns.md)
+- API reference: [`docs/api.md`](docs/api.md)
+- AG-UI adapter: [`docs/agui.md`](docs/agui.md)
+- Checkpointer and graph evolution: [`docs/checkpointer-evolution.md`](docs/checkpointer-evolution.md)
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest tests/
+uv run ruff check src/ tests/
+uv run mypy src/
+```
+
+## License
+
+MIT - see [`LICENSE`](LICENSE).