duragraph-python 0.1.0__tar.gz

duragraph_python-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,28 @@
+# CODEOWNERS - Define who reviews what
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owners for everything
+* @duragraph/maintainers
+
+# Core graph functionality
+/src/duragraph/graph.py @duragraph/core
+/src/duragraph/nodes.py @duragraph/core
+/src/duragraph/edges.py @duragraph/core
+/src/duragraph/types.py @duragraph/core
+
+# Worker and control plane integration
+/src/duragraph/worker/ @duragraph/core
+
+# Prompts module
+/src/duragraph/prompts/ @duragraph/core
+
+# CLI
+/src/duragraph/cli/ @duragraph/maintainers
+
+# CI/CD and infrastructure
+/.github/ @duragraph/maintainers
+/pyproject.toml @duragraph/maintainers
+
+# Documentation - more permissive
+/*.md @duragraph/maintainers
+/docs/ @duragraph/maintainers

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

@@ -0,0 +1,55 @@
+---
+name: Bug Report
+about: Report a bug in DuraGraph Python SDK
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+
+<!-- A clear and concise description of the bug -->
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Create a graph with...
+2. Run...
+3. See error
+
+## Expected Behavior
+
+<!-- What you expected to happen -->
+
+## Actual Behavior
+
+<!-- What actually happened -->
+
+## Code Example
+
+```python
+# Minimal code to reproduce the issue
+from duragraph import Graph, llm_node
+
+@Graph(id="example")
+class MyAgent:
+    ...
+```
+
+## Error Message
+
+```
+# Paste the full error message/traceback here
+```
+
+## Environment
+
+- OS: [e.g., macOS 14.0, Ubuntu 22.04]
+- Python version: [e.g., 3.12.0]
+- DuraGraph version: [e.g., 0.1.0]
+- Control Plane version (if applicable): [e.g., 0.1.0]
+
+## Additional Context
+
+<!-- Any other context about the problem -->

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

@@ -0,0 +1,34 @@
+---
+name: Feature Request
+about: Suggest a new feature for DuraGraph Python SDK
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+
+<!-- What problem does this feature solve? -->
+
+## Proposed Solution
+
+<!-- Describe your proposed solution -->
+
+## Example Usage
+
+```python
+# How would this feature be used?
+from duragraph import Graph, new_feature
+
+@Graph(id="example")
+class MyAgent:
+    ...
+```
+
+## Alternatives Considered
+
+<!-- What alternatives have you considered? -->
+
+## Additional Context
+
+<!-- Any other context, mockups, or references -->

duragraph_python-0.1.0/.github/labeler.yml

@@ -0,0 +1,67 @@
+# PR Labeler configuration
+# https://github.com/actions/labeler
+
+# Core functionality
+core:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/duragraph/graph.py
+          - src/duragraph/nodes.py
+          - src/duragraph/edges.py
+          - src/duragraph/types.py
+          - src/duragraph/__init__.py
+
+# Worker module
+worker:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/duragraph/worker/**/*
+
+# Prompts module
+prompts:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/duragraph/prompts/**/*
+
+# CLI
+cli:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/duragraph/cli/**/*
+
+# Tests
+tests:
+  - changed-files:
+      - any-glob-to-any-file:
+          - tests/**/*
+
+# Documentation
+documentation:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "**/*.md"
+          - docs/**/*
+
+# CI/CD
+ci:
+  - changed-files:
+      - any-glob-to-any-file:
+          - .github/**/*
+
+# Dependencies
+dependencies:
+  - changed-files:
+      - any-glob-to-any-file:
+          - pyproject.toml
+          - "*.lock"
+          - requirements*.txt
+
+# Configuration
+config:
+  - changed-files:
+      - any-glob-to-any-file:
+          - lefthook.yml
+          - .ruff.toml
+          - mypy.ini
+          - "*.toml"
+          - "*.cfg"

duragraph_python-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,38 @@
+## Description
+
+<!-- Describe your changes in detail -->
+
+## Type of Change
+
+<!-- Mark the relevant option with [x] -->
+
+- [ ] `feat` - New feature
+- [ ] `fix` - Bug fix
+- [ ] `docs` - Documentation only
+- [ ] `refactor` - Code refactoring
+- [ ] `perf` - Performance improvement
+- [ ] `test` - Adding/updating tests
+- [ ] `build` - Build system or dependencies
+- [ ] `ci` - CI/CD changes
+- [ ] `chore` - Maintenance
+
+## Related Issues
+
+<!-- Link related issues: Fixes #123, Closes #456 -->
+
+## Checklist
+
+- [ ] My code follows the project's code style
+- [ ] I have run `ruff check src/` and `ruff format src/`
+- [ ] I have added tests for my changes
+- [ ] All tests pass (`pytest tests/`)
+- [ ] I have updated documentation if needed
+- [ ] My commits follow the [conventional commits](https://www.conventionalcommits.org/) format
+
+## Breaking Changes
+
+<!-- If this is a breaking change, describe what breaks and migration steps -->
+
+## Screenshots / Examples
+
+<!-- If applicable, add screenshots or code examples -->

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

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+
+      - name: Run ruff
+        run: ruff check src/
+
+      - name: Run ruff format check
+        run: ruff format --check src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=duragraph --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: |
+          pip install twine
+          twine check dist/*

duragraph_python-0.1.0/.github/workflows/labeler.yml

@@ -0,0 +1,18 @@
+name: PR Labeler
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml

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

@@ -0,0 +1,82 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to Test PyPI instead'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && !inputs.test_pypi)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/duragraph-python
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-to-testpypi:
+    name: Publish to Test PyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.test_pypi
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/duragraph-python
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

duragraph_python-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# Documentation
+docs/_build/
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.env
+.env.local
+
+# Build artifacts
+dist/
+
+# UV lock file (optional - can be committed for reproducibility)
+# uv.lock

duragraph_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# 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.1.0] - 2024-12-29
+
+### Added
+- Initial package structure
+- `@Graph` class decorator for defining workflows
+- Node decorators: `@llm_node`, `@tool_node`, `@router_node`, `@human_node`, `@node`
+- `@entrypoint` decorator for marking graph entry points
+- Edge definitions with `>>` operator support
+- `Worker` class for control plane integration
+- `PromptStore` client for prompt management
+- `@prompt` decorator for attaching prompts to nodes
+- CLI commands: `init`, `dev`, `deploy`, `visualize`
+- Type definitions: `State`, `Message`, `HumanMessage`, `AIMessage`, `ToolMessage`, `Event`, `RunResult`
+- GitHub Actions CI/CD for PyPI publishing
+- Lefthook git hooks for pre-commit and commit message validation
+- Conventional commits enforcement
+- Apache 2.0 license
+- PEP 561 type hints support (py.typed marker)
+
+[Unreleased]: https://github.com/duragraph/duragraph-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/duragraph/duragraph-python/releases/tag/v0.1.0

duragraph_python-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,173 @@
+# Contributing to DuraGraph Python SDK
+
+Thank you for your interest in contributing to DuraGraph! This document provides guidelines and conventions for contributing.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/duragraph-python.git
+   cd duragraph-python
+   ```
+
+3. Install dependencies with uv:
+   ```bash
+   uv sync --all-extras
+   ```
+
+4. Install git hooks:
+   ```bash
+   lefthook install
+   ```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=duragraph --cov-report=html
+
+# Run specific test
+pytest tests/test_graph.py -v
+```
+
+### Linting & Formatting
+
+```bash
+# Check linting
+ruff check src/
+
+# Auto-fix linting issues
+ruff check src/ --fix
+
+# Format code
+ruff format src/
+
+# Type checking
+mypy src/duragraph
+```
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow this format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Commit Types
+
+| Type       | Description                                          | Example                                    |
+|------------|------------------------------------------------------|--------------------------------------------|
+| `feat`     | New feature                                          | `feat(graph): add subgraph support`        |
+| `fix`      | Bug fix                                              | `fix(worker): handle connection timeout`   |
+| `docs`     | Documentation only                                   | `docs: update installation guide`          |
+| `style`    | Code style (formatting, semicolons, etc.)            | `style: fix indentation in nodes.py`       |
+| `refactor` | Code change that neither fixes a bug nor adds feature| `refactor(cli): simplify command parsing`  |
+| `perf`     | Performance improvement                              | `perf(graph): optimize node lookup`        |
+| `test`     | Adding or updating tests                             | `test(worker): add registration tests`     |
+| `build`    | Build system or dependencies                         | `build: update httpx to 0.28`              |
+| `ci`       | CI/CD configuration                                  | `ci: add Python 3.13 to test matrix`       |
+| `chore`    | Maintenance tasks                                    | `chore: update .gitignore`                 |
+| `revert`   | Revert a previous commit                             | `revert: feat(graph): add subgraph support`|
+
+### Scopes
+
+Common scopes for this project:
+
+- `graph` - Graph decorator and execution
+- `nodes` - Node decorators (llm_node, tool_node, etc.)
+- `edges` - Edge definitions
+- `worker` - Worker and control plane integration
+- `prompts` - Prompt store and management
+- `cli` - Command-line interface
+- `types` - Type definitions
+- `deps` - Dependencies
+
+### Examples
+
+```bash
+# Feature
+git commit -m "feat(graph): add async streaming support"
+
+# Bug fix with issue reference
+git commit -m "fix(worker): prevent duplicate registration
+
+Fixes #123"
+
+# Breaking change
+git commit -m "feat(nodes)!: rename @llm to @llm_node
+
+BREAKING CHANGE: The @llm decorator has been renamed to @llm_node for clarity."
+
+# Documentation
+git commit -m "docs(readme): add streaming example"
+```
+
+## Pull Request Guidelines
+
+### Before Submitting
+
+- [ ] Code passes all tests (`pytest tests/`)
+- [ ] Code passes linting (`ruff check src/`)
+- [ ] Code is formatted (`ruff format src/`)
+- [ ] Commit messages follow convention
+- [ ] Documentation is updated if needed
+- [ ] CHANGELOG.md is updated for user-facing changes
+
+### PR Title
+
+PR titles should also follow the commit convention:
+
+```
+feat(graph): add subgraph support
+```
+
+### PR Labels
+
+PRs are automatically labeled based on files changed:
+
+| Label          | Files                              |
+|----------------|------------------------------------|
+| `core`         | `src/duragraph/graph.py`, `nodes.py`, `edges.py` |
+| `worker`       | `src/duragraph/worker/`            |
+| `prompts`      | `src/duragraph/prompts/`           |
+| `cli`          | `src/duragraph/cli/`               |
+| `tests`        | `tests/`                           |
+| `docs`         | `*.md`, `docs/`                    |
+| `ci`           | `.github/`                         |
+| `dependencies` | `pyproject.toml`, `*.lock`         |
+
+### Review Process
+
+1. All PRs require at least one approval
+2. CI must pass (lint, test, build)
+3. Maintainers may request changes
+4. Squash merge is preferred for clean history
+
+## Releasing
+
+Releases are handled by maintainers:
+
+1. Update version in `pyproject.toml`
+2. Update `CHANGELOG.md`
+3. Create a GitHub release with tag `vX.Y.Z`
+4. GitHub Actions automatically publishes to PyPI
+
+## Code of Conduct
+
+Be respectful and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/).
+
+## Questions?
+
+- Open a [GitHub Discussion](https://github.com/duragraph/duragraph-python/discussions)
+- Check existing [Issues](https://github.com/duragraph/duragraph-python/issues)