actionable-errors 0.1.0__tar.gz

actionable_errors-0.1.0/.envrc

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+# Auto-activate uv virtual environment
+if ! has uv; then
+    echo "❌ uv is not installed. Please install it first:"
+    echo "   curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
+# Create virtual environment if it doesn't exist
+if [[ ! -d ".venv" ]]; then
+    echo "📦 Creating virtual environment with uv..."
+    uv venv
+fi
+
+# Activate the virtual environment
+source .venv/bin/activate
+# Source .envrc.local if present (for user/machine-specific settings)
+if [[ -f ".envrc.local" ]]; then
+    echo "🔒 Sourcing .envrc.local..."
+    source .envrc.local
+fi
+
+# Sync dependencies (including dev dependencies)
+echo "🔄 Syncing dependencies..."
+# Use --all-extras for maximum compatibility with any dependency structure
+# (works with both dependency-groups and optional-dependencies)
+uv sync --all-extras
+
+# Git configuration for this project (optional)
+# Uncomment and customize as needed or add to .envrc.local:
+# git config user.name "Your Name"
+# git config user.email "your.email@example.com"
+
+# Install pre-commit hooks if they don't exist
+if [[ -f ".pre-commit-config.yaml" ]] && ! uv run pre-commit --version >/dev/null 2>&1; then
+    echo "🪝 Installing pre-commit hooks..."
+    uv run pre-commit install
+fi
+
+# Export environment variables
+export PYTHONPATH="${PWD}/src:${PYTHONPATH}"
+export UV_PROJECT_ENVIRONMENT="${PWD}/.venv"
+
+echo "✅ Environment activated!"
+echo "📁 Virtual environment: ${VIRTUAL_ENV}"
+echo "🐍 Python: $(python --version)"
+echo "📦 uv: $(uv --version)"
+
+# Show available commands
+echo ""
+echo "🚀 Available commands:"
+echo "   uv run pytest                 # Run tests"
+echo "   uv run pytest --cov           # Run tests with coverage report"
+echo "   uv run pytest --cov --cov-report=html  # Generate HTML coverage report"
+echo "   uv run ruff check             # Lint code"
+echo "   uv run ruff format            # Format code"
+echo "   uv run mypy src/              # Type check"
+echo "   uv run pre-commit run --all   # Run all pre-commit hooks"
+# Show available taskipy commands if task is available
+if has task; then
+    echo ""
+    echo "📝 Available taskipy commands (via 'task'):"
+    task --list
+fi

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

@@ -0,0 +1,38 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Who / What / Why
+
+- **WHO:** Who is affected? (e.g., library consumer, AI agent, operator)
+- **WHAT:** What behavior is broken or unexpected?
+- **WHY:** Why does it matter? What's the impact?
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full error message if applicable.
+
+## Environment
+
+- OS: [e.g., Ubuntu 24.04]
+- Python version: [e.g., 3.12.3]
+- actionable-errors version: [e.g., 0.1.0]
+- Install method: [pip, uv, from source]
+
+## Additional Context
+
+Any other context — stack traces, minimal reproduction script, etc.

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

@@ -0,0 +1,30 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Who / What / Why
+
+- **WHO:** Who needs this? (e.g., library consumer, AI agent, operator)
+- **WHAT:** What capability or behavior is needed?
+- **WHY:** Why does it matter? What problem does it solve?
+
+## Proposed Solution
+
+How do you think it should work?
+
+## Zero-Dependency Constraint
+
+Can this be implemented with stdlib only? If not, explain why an exception
+is warranted and what the dependency cost would be to consumers.
+
+## Alternatives Considered
+
+Any other approaches you thought about and why they're less ideal.
+
+## Additional Context
+
+Anything else — code samples, related issues, etc.

actionable_errors-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+# Pull Request
+
+## Summary
+<!-- One paragraph: what this PR does and why -->
+
+## Changes
+<!-- Bullet list of changes -->
+
+## Testing
+<!-- How were these changes verified? -->
+- [ ] All existing tests pass (`task check`)
+- [ ] New tests added for new behavior
+- [ ] Coverage target maintained (100%)
+
+## Checklist
+- [ ] `from __future__ import annotations` at top of every new module
+- [ ] mypy strict passes
+- [ ] ruff lint + format passes
+- [ ] No runtime dependencies added (stdlib only)

actionable_errors-0.1.0/.github/secret_scanning.yml

@@ -0,0 +1,2 @@
+paths-ignore:
+  - "tests/**"

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

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: uv run mypy src/
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=actionable_errors --cov-report=term-missing --cov-report=json
+
+      - name: Extract coverage percentage
+        if: github.ref == 'refs/heads/main'
+        run: |
+          COVERAGE=$(python -c "import json; print(int(json.load(open('coverage.json'))['totals']['percent_covered']))")
+          echo "COVERAGE_PCT=$COVERAGE" >> $GITHUB_ENV
+
+      - name: Update coverage badge
+        if: github.ref == 'refs/heads/main'
+        uses: schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: ${{ vars.COVERAGE_GIST_ID }}
+          filename: actionable-errors-coverage.json
+          label: coverage
+          message: ${{ env.COVERAGE_PCT }}%
+          valColorRange: ${{ env.COVERAGE_PCT }}
+          minColorRange: 50
+          maxColorRange: 100

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

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing (OIDC)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest --cov=actionable_errors --cov-report=term-missing
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi  # GitHub Environment for deployment protection
+    permissions:
+      id-token: write  # OIDC token for PyPI trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

actionable_errors-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# direnv
+.direnv/
+.envrc.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+.coverage
+coverage.json
+htmlcov/
+
+# mypy / ruff / pytest caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Direnv local environment variables
+.envrc.local

actionable_errors-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--strict]

actionable_errors-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery and unwelcome sexual attention
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

actionable_errors-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing
+
+Thanks for your interest in contributing to actionable-errors. This document
+covers the development setup, coding standards, testing philosophy, and
+PR process.
+
+---
+
+## Development Setup
+
+```bash
+# Clone
+git clone https://github.com/grimlor/actionable-errors.git
+cd actionable-errors
+
+# Install with dev dependencies (creates .venv automatically)
+uv sync --extra dev
+
+# Optional: auto-activate venv
+direnv allow
+```
+
+## Running Checks
+
+All checks must pass before submitting a PR:
+
+```bash
+task check          # runs lint → type → test
+```
+
+Or individually:
+
+```bash
+task lint           # ruff check src/ tests/
+task format         # ruff format src/ tests/
+task type           # mypy strict mode
+task test           # pytest -v
+```
+
+## Code Style
+
+- **Python 3.12+** — use modern syntax (`X | Y` unions, `@dataclass`).
+- **`from __future__ import annotations`** at the top of every module.
+- **ruff** handles formatting and import sorting. Don't fight it.
+- **mypy strict** — all functions need type annotations. No `Any` unless
+  you have a good reason and document it.
+- **Line length:** 99 characters (configured in `pyproject.toml`).
+- **Quote style:** double quotes.
+
+## Zero-Dependency Constraint
+
+This package has **zero runtime dependencies** — stdlib only. This is a
+hard architectural constraint, not a preference. `actionable-errors` sits
+at the bottom of every dependency tree. Adding a runtime dependency would
+transitively infect every consumer.
+
+Dev dependencies (ruff, mypy, pytest, etc.) are fine — they don't ship.
+
+## Testing Standards
+
+Tests are the living specification. Every test class documents a behavioral
+requirement, not a code structure.
+
+### Test Class Structure
+
+```python
+class TestYourFeature:
+    """
+    REQUIREMENT: One-sentence summary of the behavioral contract.
+
+    WHO: Who depends on this behavior (calling code, operator, AI agent)
+    WHAT: What the behavior is, including failure modes
+    WHY: What breaks if this contract is violated
+
+    MOCK BOUNDARY:
+        Mock:  nothing — this package is pure computation
+        Real:  all classes and functions under test
+        Never: construct expected output and assert on the construction
+    """
+
+    def test_descriptive_name_of_scenario(self) -> None:
+        """
+        Given some precondition
+        When an action is taken
+        Then an observable outcome occurs
+        """
+        ...
+```
+
+### Key Principles
+
+1. **Mock I/O boundaries, not implementation.** Since this package has no
+   I/O (stdlib only, no network, no filesystem), most tests will have
+   `Mock: nothing` in their mock boundary contract.
+
+2. **Failure specs matter.** For every happy path, ask: what goes wrong?
+   Write specs for those failure modes. An unspecified failure is an
+   unhandled failure.
+
+3. **Missing spec = missing requirement.** If you find a bug, the first
+   step is always adding the test that should have caught it, then fixing
+   the code to pass that test.
+
+4. **Every assertion includes a diagnostic message.** Bare assertions are
+   not permitted.
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the three-audience
+error design philosophy and module responsibilities.
+
+## Commit Messages
+
+Use clear, imperative commit messages:
+
+```
+Add credential sanitizer with configurable patterns
+
+- Eight built-in regex patterns for common credential formats
+- Consumer-extensible pattern registration
+- 15 tests covering all built-in patterns and custom registration
+```
+
+## Pull Requests
+
+1. **Branch from `main`.**
+2. **All checks must pass** — `task check` (lint + type + test).
+3. **Include tests** for any new behavior or bug fix.
+4. **One concern per PR** — don't mix a new feature with unrelated refactoring.
+5. **No runtime dependencies** — this is a hard constraint.
+6. **Describe what and why** in the PR description.
+
+## Reporting Issues
+
+When filing an issue:
+
+- **Bug:** Include the error message, what you expected, and steps to
+  reproduce. Include the Python version and how actionable-errors was
+  installed.
+- **Feature request:** Describe the problem you're trying to solve, not
+  just the solution you have in mind. Note whether it can be done with
+  stdlib only.

actionable_errors-0.1.0/LICENSE

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

actionable_errors-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: actionable-errors
+Version: 0.1.0
+Summary: Three-audience error framework: typed errors for code, actionable suggestions for humans, tool guidance for AI agents
+Project-URL: Repository, https://github.com/grimlor/actionable-errors
+Author: grimlor
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pre-commit<5,>=4; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: taskipy<2,>=1.14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# actionable-errors
+
+Three-audience error framework for Python.
+
+Every `ActionableError` speaks to three audiences simultaneously:
+
+| Audience | Uses | Provided by |
+|----------|------|-------------|
+| **Calling code** | Typed `ErrorType` for routing (retry? escalate? ignore?) | `ErrorType(StrEnum)` — 8 base categories |
+| **Human operator** | `suggestion` + `Troubleshooting` steps | Frozen dataclasses with actionable text |
+| **AI agent** | `AIGuidance` with concrete next tool calls | Frozen dataclass with tool suggestions |
+
+## Install
+
+```bash
+pip install actionable-errors
+```
+
+**Zero runtime dependencies** — stdlib only. Sits at the bottom of every dependency tree.
+
+## Quick Start
+
+```python
+from actionable_errors import (
+    ActionableError,
+    AIGuidance,
+    ToolResult,
+    from_exception,
+    sanitize,
+)
+
+# Domain-specific factory with built-in defaults
+error = ActionableError.authentication(
+    service="Azure DevOps",
+    raw_error="401 Unauthorized",
+)
+print(error.suggestion)    # "Check your credentials and try again."
+print(error.ai_guidance)   # AIGuidance(action_required="Re-authenticate", command="az login")
+
+# Auto-classify any exception
+try:
+    raise ConnectionError("Connection refused")
+except Exception as exc:
+    ae = from_exception(exc, service="Kusto", operation="query")
+    print(ae.error_type)   # "connection"
+
+# Typed result envelope for MCP tool responses
+result = ToolResult.ok(data={"items": 42})
+result = ToolResult.fail(error=error)     # extracts error_type + suggestion
+
+# Credential sanitization
+clean = sanitize('password="hunter2" token=abc123')
+# → 'password="***" token=***'
+```
+
+## Extending ErrorType
+
+Python `StrEnum` can't be subclassed once it has members, so extend via composition:
+
+```python
+from enum import StrEnum
+from actionable_errors import ActionableError
+
+class RAGErrorType(StrEnum):
+    EMBEDDING = "embedding"
+    INDEX = "index"
+
+error = ActionableError(
+    error="Vector store unavailable",
+    error_type=RAGErrorType.INDEX,
+    service="pinecone",
+    suggestion="Check Pinecone cluster status.",
+)
+```
+
+## Factories
+
+Eight domain-specific factories with sensible defaults:
+
+| Factory | Key Parameters |
+|---------|---------------|
+| `.authentication(service, raw_error)` | Default suggestion + AI guidance |
+| `.configuration(field_name, reason)` | — |
+| `.connection(service, url, raw_error)` | — |
+| `.timeout(service, operation, timeout_seconds)` | — |
+| `.permission(service, resource, raw_error)` | — |
+| `.validation(service, field_name, reason)` | — |
+| `.not_found(service, resource_type, resource_id, raw_error)` | — |
+| `.internal(service, operation, raw_error)` | — |
+
+All factories accept optional `suggestion`, `ai_guidance`, and `troubleshooting` kwargs.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run all checks
+task check  # lint → type → test (90 tests, 100% coverage)
+```
+
+## License
+
+MIT