lionherd-core 1.0.0a4__tar.gz

lionherd_core-1.0.0a4/.coveragerc

@@ -0,0 +1,34 @@
+[run]
+source = src/lionherd_core
+omit =
+    */tests/*
+    */test_*
+    */__pycache__/*
+    */site-packages/*
+    .venv/*
+
+[report]
+precision = 2
+show_missing = True
+skip_covered = False
+sort = Cover
+
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    if self.debug:
+    if settings.DEBUG
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if False:
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    class .*\bProtocol\):
+    @(abc\.)?abstractmethod
+
+[html]
+directory = htmlcov
+
+[json]
+output = coverage.json

lionherd_core-1.0.0a4/.github/workflows/ci.yml

@@ -0,0 +1,190 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # =============================================================================
+  # Linting and formatting checks
+  # =============================================================================
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies (workspace dev deps + all package extras)
+        run: uv sync --all-extras
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+  # =============================================================================
+  # Type checking
+  # =============================================================================
+  typecheck:
+    name: Type Check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies (workspace dev deps + all package extras)
+        run: uv sync --group dev --all-extras
+
+      - name: Run mypy
+        run: uv run mypy src/lionherd_core
+        continue-on-error: true # Don't block CI on type errors initially
+
+  # =============================================================================
+  # Test suite (matrix: Python versions)
+  # =============================================================================
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    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 uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies (workspace dev deps + all package extras)
+        run: uv sync --group dev --all-extras
+
+      - name: Run tests (parallel execution)
+        if: matrix.python-version != '3.11'
+        run: |
+          uv run pytest tests/ \
+            --junitxml=junit.xml \
+            --tb=short \
+            -n auto
+
+      - name: Run tests with coverage (Python 3.11 only)
+        if: matrix.python-version == '3.11'
+        run: |
+          uv run pytest tests/ \
+            --cov=src/lionherd_core \
+            --cov-report=xml \
+            --cov-report=term-missing:skip-covered \
+            --junitxml=junit.xml \
+            --tb=short \
+            -n auto
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: |
+            junit.xml
+            coverage.xml
+
+  # =============================================================================
+  # Build check (ensure package builds correctly)
+  # =============================================================================
+  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.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # =============================================================================
+  # All checks must pass (required status check)
+  # =============================================================================
+  ci-success:
+    name: CI Success
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test, build]
+    if: always()
+    steps:
+      - name: Check all jobs
+        run: |
+          if [ "${{ needs.lint.result }}" != "success" ]; then
+            echo "Linting failed"
+            exit 1
+          fi
+          if [ "${{ needs.test.result }}" != "success" ]; then
+            echo "Tests failed"
+            exit 1
+          fi
+          if [ "${{ needs.build.result }}" != "success" ]; then
+            echo "Build failed"
+            exit 1
+          fi
+          # typecheck is allowed to fail (continue-on-error)
+          echo "All required checks passed!"

lionherd_core-1.0.0a4/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  schedule:
+    - cron: "0 0 * * 0"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["python"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+# filepath: .github/workflows/codeql-analysis.yml

lionherd_core-1.0.0a4/.github/workflows/pre-commit.yml

@@ -0,0 +1,39 @@
+name: Pre-commit Checks
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    name: Pre-commit Hooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for proper diff
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies (workspace dev deps + all package extras)
+        run: uv sync --group dev --all-extras
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            pre-commit-${{ runner.os }}-
+
+      - name: Run pre-commit (changed files only)
+        run: uv run pre-commit run --show-diff-on-failure --color=always --from-ref origin/${{ github.base_ref }} --to-ref HEAD

lionherd_core-1.0.0a4/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv sync --all-extras
+
+      - name: Run tests
+        run: |
+          source .venv/bin/activate
+          uv run pytest --asyncio-mode=auto --maxfail=1 --disable-warnings tests/
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install twine
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_KEY }}
+        run: uv run twine upload dist/*

lionherd_core-1.0.0a4/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+targets/
+node_modules/
+
+# Virtual environments
+.venv
+
+*.gitignore
+.benchmarks/
+.*_cache/
+*.khive/
+*.hypothesis/
+
+*.coverage
+*coverage.json
+
+*.DS_Store
+data/
+
+site/
+
+node_modules/

lionherd_core-1.0.0a4/.markdownlint-cli2.yaml

@@ -0,0 +1,7 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+
+config:
+  # MD024: Multiple headings with the same content
+  # Disabled for CHANGELOG.md where duplicate "Added" sections are expected
+  MD024: false

lionherd_core-1.0.0a4/.markdownlint.json

@@ -0,0 +1,6 @@
+{
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  }
+}

lionherd_core-1.0.0a4/.pre-commit-config.yaml

@@ -0,0 +1,117 @@
+# Pre-commit hooks for lionherd monorepo
+# Docs: https://pre-commit.com/
+# Install: pre-commit install
+# Run: pre-commit run --all-files
+# Update: pre-commit autoupdate
+
+default_language_version:
+  python: python3.11
+  node: system
+
+repos:
+  # =============================================================================
+  # Basic file checks (fast, no dependencies)
+  # =============================================================================
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: \.md$
+      - id: end-of-file-fixer
+        exclude: \.svg$
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: check-yaml
+        args: [--unsafe] # Allow custom YAML tags
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-case-conflict
+      - id: detect-private-key
+
+  # =============================================================================
+  # TOML formatting (before Python, as it may format pyproject.toml)
+  # =============================================================================
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+
+  # =============================================================================
+  # Python: Ruff (linter BEFORE formatter)
+  # =============================================================================
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.2
+    hooks:
+      # Linter with auto-fix
+      - id: ruff
+        args: [--fix]
+        types_or: [python, pyi]
+      # Formatter
+      - id: ruff-format
+        types_or: [python, pyi]
+
+  # =============================================================================
+  # Rust: Clippy linter
+  # =============================================================================
+  - repo: https://github.com/doublify/pre-commit-rust
+    rev: v1.0
+    hooks:
+      - id: fmt
+        name: cargo fmt
+        args: [--all, --]
+      - id: clippy
+        name: cargo clippy
+        args: [--all-targets, --all-features, --, -D, warnings]
+
+  # =============================================================================
+  # Next.js / TypeScript: ESLint
+  # =============================================================================
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v9.17.0
+    hooks:
+      - id: eslint
+        files: \.(js|jsx|ts|tsx)$
+        types: [file]
+        args: [--fix, --max-warnings=0]
+        additional_dependencies:
+          - eslint@9.17.0
+          - eslint-config-next@15.1.3
+          - typescript@5.7.2
+          - "@typescript-eslint/parser@8.18.0"
+          - "@typescript-eslint/eslint-plugin@8.18.0"
+
+  # =============================================================================
+  # JSON/YAML formatting
+  # =============================================================================
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [json, yaml]
+        exclude: ^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$
+
+  # =============================================================================
+  # Markdown linting
+  # =============================================================================
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.18.1
+    hooks:
+      - id: markdownlint-cli2
+        args: [--fix]
+        exclude: ^\.github/
+
+# CI optimization: only run on changed files
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit.com hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ""
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false

lionherd_core-1.0.0a4/.python-version

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

lionherd_core-1.0.0a4/CHANGELOG.md

@@ -0,0 +1,145 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0a4](https://github.com/khive-ai/lionherd-core/releases/tag/v1.0.0-alpha4) - 2025-11-11
+
+### Changed
+
+- **Error Handling**: `Graph`, `Flow`, and `Pile` now raise `NotFoundError` and
+  `ExistsError` instead of `ValueError` for missing/duplicate items (#129, #131,
+  #133). Exception metadata (`.details`, `.retryable`, `.__cause__`) is now
+  preserved for retry logic. Update exception handlers from `except ValueError`
+  to `except NotFoundError` or `except ExistsError` as appropriate.
+  - `Pile.pop()` now raises `NotFoundError` (was `ValueError`) for consistency
+    with `Pile.get()` and `Pile.remove()`.
+- **Performance**: `Pile` methods now use single-lookup pattern (try/except vs
+  if/check) for 50% performance improvement on failed lookups (#128).
+- **Module Organization**: Async utilities consolidated to `libs/concurrency` for
+  cleaner structure (#114).
+
+### Removed
+
+- **BREAKING**: `Graph.get_node()` and `Graph.get_edge()` removed in favor of
+  direct Pile access (#117, #124, #132).
+
+  **Migration**:
+
+  ```python
+  # Before
+  node = graph.get_node(node_id)
+  edge = graph.get_edge(edge_id)
+
+  # After
+  node = graph.nodes[node_id]
+  edge = graph.edges[edge_id]
+  ```
+
+  **Rationale**: Eliminates unnecessary wrapper methods. Direct Pile access is
+  more Pythonic and consistent with dict/list-like interfaces.
+
+### Fixed
+
+- **BREAKING**: `Element.to_dict()` `created_at_format` now applies to ALL modes
+  (#39). DB mode default changed from `isoformat` (string) to `datetime` (object)
+  for ORM compatibility. Migration: use `to_dict(mode='db',
+  created_at_format='isoformat')` for backward compatibility.
+
+### Added
+
+- **Tutorial Infrastructure**: 29 executable tutorials covering concurrency
+  patterns, schema/string handlers, ln utilities, and advanced workflows (#99-106).
+  Includes circuit breakers, deadline management, fuzzy matching, pipelines, and
+  resource lifecycle patterns.
+- **API Documentation**: Complete reference docs and Jupyter notebooks for all
+  base types (Element, Node, Pile, Progression, Flow, Graph, Event, Broadcaster,
+  EventBus), types system (HashableModel, Operable/Spec, Sentinel), and libs
+  (concurrency, schema, string, ln utilities) (#39, #43-46, #52, #54-59).
+- **LNDL Documentation**: Complete API documentation and Jupyter notebooks for LNDL
+  (Language InterOperable Network Directive Language) system (#53). Includes 6
+  module docs (types, parser, resolver, fuzzy, prompt, errors) and 6 reference
+  notebooks with 100% execution coverage (185/185 cells).
+- **Node Features**: Content constraint (dict|Serializable|BaseModel|None, no
+  primitives) and embedding serialization support for pgvector + JSONB (#50, #113).
+- **Pile.pop() default**: Optional default parameter for safer fallback, consistent
+  with `dict.pop()` behavior (#118, #123).
+- **Test Coverage**: Race condition tests for Event timeout/exception/cancellation
+  scenarios and fuzzy JSON kwargs regression tests (#32, #107, #112).
+
+## [1.0.0a3](https://github.com/khive-ai/lionherd-core/releases/tag/v1.0.0-alpha3) - 2025-11-06
+
+### Fixed
+
+- **Memory Leaks**: `EventBus` (#22) and `Broadcaster` (#24) now use
+  `weakref` for automatic callback cleanup. Prevents unbounded growth in
+  long-running apps.
+- **TOCTOU Races**: `Graph.add_edge()` (#21) and `Event.invoke()` (#26)
+  synchronized with decorators. Eliminates 10% duplicate execution rate
+  under concurrency.
+- **LNDL Guard**: `ensure_no_action_calls()` (#23) prevents `ActionCall`
+  persistence. Recursively detects placeholders in nested models/collections.
+- **Backend Agnostic**: `Event._async_lock` now anyio-based (was
+  `asyncio.Lock`). Enables Trio support.
+
+### Changed
+
+- **Event Idempotency**: Clarified `invoke()` caches results after
+  COMPLETED/FAILED. Use `as_fresh_event()` for retry.
+
+### Added
+
+- Race/memory leak tests with GC validation. 100% coverage for guards.
+
+## [1.0.0a2](https://github.com/khive-ai/lionherd-core/releases/tag/v1.0.0-alpha2) - 2025-11-05
+
+### Added
+
+- **Event Timeout Support**: Optional `timeout` field with validation.
+  Converts `TimeoutError` to `LionherdTimeoutError` with `status=CANCELLED`,
+  `retryable=True`.
+- **PriorityQueue**: Async priority queue using `heapq` + anyio primitives
+  with `put()`, `get()`, `put_nowait()`, `get_nowait()`. 100% test coverage.
+- **LNDL Reserved Keyword Validation**: Python keyword checking for action
+  names with `UserWarning`.
+
+### Fixed
+
+- **PriorityQueue Deadlock**: `get_nowait()` now notifies waiting putters,
+  preventing deadlock with bounded queues.
+- **LNDL**: Fixed typo in error messages and improved system prompt examples.
+
+### Changed
+
+- **Flow Architecture** (breaking): Composition over inheritance. `add()` →
+  `add_progression()`, `pile` → `items`.
+- **Copy Semantics** (breaking): `with_updates()` now uses
+  `Literal["shallow", "deep"] | None` instead of two booleans.
+- **Event Documentation**: Simplified docstrings, added `@final` to
+  `invoke()`, moved rationale to tests.
+- **EventStatus**: Uses `lionherd_core.types.Enum` instead of `(str, Enum)`
+  for `Allowable` protocol support.
+
+## [1.0.0a1](https://github.com/khive-ai/lionherd-core/releases/tag/v1.0.0-alpha1) - 2025-11-03
+
+### Added
+
+- **LNDL Action Syntax**: Added support for tool/function invocations within
+  LNDL responses using `<lact>` tags. Supports both namespaced actions
+  (`<lact Model.field alias>function(...)</lact>`) for mixing with lvars and
+  direct actions (`<lact name>function(...)</lact>`) for entire output.
+  Includes fuzzy matching support and complete validation lifecycle with
+  re-validation after action execution.
+- Added `py.typed` marker file for PEP 561 compliance to enable type checking support
+
+## [1.0.0a0](https://github.com/khive-ai/lionherd-core/releases/tag/v1.0.0-alpha) - 2025-11-02
+
+### Added
+
+- Initial release of lionherd-core
+- Core orchestration framework
+- Base abstractions and protocols