Skip to main content

Read this README in Russian

🚀 Error Narrator

PyPI version

Error Narrator is a Python library that uses AI to provide clear, human-readable explanations for Python exceptions and tracebacks. Instead of just getting a stack trace, you get a structured, educational breakdown of what went wrong, right in your console.

Error Narrator Screenshot

The library is multilingual, currently supporting English (default) and Russian.

📦 Features

  • 🤖 AI-Powered Explanations: Uses language models from Gradio or OpenAI to explain errors.
  • 📝 Structured Output: Provides a clear, markdown-formatted explanation with:
    • 🎯 Root Cause: What caused the error.
    • 📍 Error Location: Pinpoints the exact file and line.
    • 🛠️ Suggested Fix: Offers a code diff for a potential solution.
    • 🎓 A Learning Moment: Explains the underlying concepts to prevent future mistakes.
  • 🎨 Rich Console Output: Uses the rich library to print beautiful, colorized output in the terminal.
  • ⚡ Async Support: Provides asynchronous methods (*_async) for non-blocking operations.
  • 💾 Caching: Caches explanations for identical tracebacks to speed up repeated runs and reduce API calls.
  • 🌐 Multilingual: Supports explanations in English (en) and Russian (ru).

💾 Installation

pip install error-narrator

📝 How to Use

1. 🔑 API Key Configuration

The library supports two providers: gradio (default) and openai.

  • Gradio (Default & Free): This provider uses public, community-hosted models on Hugging Face Spaces. An API key (Hugging Face User Access Token) is optional for most public models but may be required for private models or to increase rate limits. You can get a token from your Hugging Face account settings.
  • OpenAI (Higher Quality & Paid): This provider uses official OpenAI models. An API key from your OpenAI dashboard is mandatory.

💡 Tip: The library will automatically detect API keys set as environment variables:

  • HUGGINGFACE_API_KEY for Gradio (optional).
  • OPENAI_API_KEY for OpenAI (required).

How to Set Environment Variables

You can set these variables for your current terminal session or add them to your shell's profile file (e.g., .bashrc, .zshrc, or your system's environment variable settings) for them to be permanent.

On macOS/Linux:

export HUGGINGFACE_API_KEY="your-key-here"

On Windows (Command Prompt):

set HUGGINGFACE_API_KEY="your-key-here"

On Windows (PowerShell):

$env:HUGGINGFACE_API_KEY="your-key-here"

2. ⚙️ Basic Usage

Here is a simple example of how to use ErrorNarrator. The library will automatically catch exceptions within a try...except block and explain them.

By default, the explanation will be in English.

import traceback
from error_narrator import ErrorNarrator

# The narrator will automatically look for the HUGGINGFACE_API_KEY environment variable
# if no api_key is provided.
narrator = ErrorNarrator() 

try:
    # Some code that might raise an error
    result = 1 / 0
except Exception:
    # Get the traceback as a string
    traceback_str = traceback.format_exc()
    # Get the explanation and print it to the console
    narrator.explain_and_print(traceback_str)

3. 🌍 Getting Explanations in Russian

To get explanations in a different language, use the language parameter during initialization.

# ...
# Initialize with Russian language support
narrator = ErrorNarrator(language="ru")
# ...

4. 🏷️ Using a specific provider (e.g., OpenAI)

You can also specify a provider and pass the API key directly.

narrator = ErrorNarrator(
    provider="openai",
    api_key="your-openai-api-key"
)
# ...

5. 🔄 Gradio Provider: Model List and Rotation

By default, the gradio provider uses a predefined list of public models and tries them in a random order for each request. This rotation and retry system increases the chances of getting a successful response.

The best way to customize the model list is to pass your own list directly during initialization using the models parameter. This gives you full control without editing any package files.

# Provide a custom list of models for rotation
my_favorite_models = [
    "hysts/mistral-7b",
    "Tblue/gemma-7b-it",
    "your-username/your-own-model"
]

narrator = ErrorNarrator(
    provider="gradio",
    models=my_favorite_models
)

How to Use a Single Specific Model

If you want to disable rotation and use only one model, you can use the model_id parameter as a convenient shortcut.

# This will ONLY use the specified model
narrator = ErrorNarrator(provider="gradio", model_id="hysts/mistral-7b")

How to Edit the Default Model List

If you want to change the default behavior for all your projects, you can edit the gradio_models.py file directly in your Python site-packages directory. This is generally not recommended unless you know what you are doing.

🤝 Development

Contributions are welcome! Please feel free to submit a pull request or open an issue.

Metadata

Release files for error-narrator 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for error-narrator 0.3.2
File Size Uploaded Provenance Actions
error_narrator-0.3.2.tar.gz 8.2 kB Without provenance Details for error_narrator-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for error-narrator 0.3.2
File Interpreter ABI Platform Actions
error_narrator-0.3.2-py3-none-any.whl Python 3 none any Details for error_narrator-0.3.2-py3-none-any.whl

Total release size: 17.5 kB

Release files / error_narrator-0.3.2.tar.gz

Download URL error_narrator-0.3.2.tar.gz
Size 8.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1b105011dbf893ddc3a8490dc90ea4a89ccbed58bdd51fbf8f569304e5dbf6e0
BLAKE2b-256 checksum
How to use checksums
33e2d46b8bdaa3780a23fb0028ed321022e44eab2caf08be69aaba0b9c5a632a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.4

Release files / error_narrator-0.3.2-py3-none-any.whl

Download URL error_narrator-0.3.2-py3-none-any.whl
Size 9.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3dad529b546fe3efab50f4fefd1a7e34aaf98759b8d5ffd5963df4f38c7c5493
BLAKE2b-256 checksum
How to use checksums
c69fe48eea7325ff3a613183bc46e8105d9a0d2dba8698ea1cabc03fe60cc166
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.4

Security for error-narrator 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page