From a1e862550c0b5f61b6c8782dde9aa3b168ce0405 Mon Sep 17 00:00:00 2001
From: Kai Chappell <git@kschappell.com>
Date: Tue, 3 Feb 2026 16:15:55 +0000
Subject: [PATCH] feat(core): add exception hierarchy

Implement VeritextError base class and specialised exceptions:
MetricError, ValidationError, BenchmarkError, ConfigurationError, DependencyError.
---
 src/veritext/__init__.py        |  4 +++
 src/veritext/core/__init__.py   | 36 ++++++++++++++++++++++++++
 src/veritext/core/exceptions.py | 45 +++++++++++++++++++++++++++++++++
 src/veritext/py.typed           |  0
 4 files changed, 85 insertions(+)
 create mode 100644 src/veritext/__init__.py
 create mode 100644 src/veritext/core/__init__.py
 create mode 100644 src/veritext/core/exceptions.py
 create mode 100644 src/veritext/py.typed

diff --git a/src/veritext/__init__.py b/src/veritext/__init__.py
new file mode 100644
index 0000000..c1450c7
--- /dev/null
+++ b/src/veritext/__init__.py
@@ -0,0 +1,4 @@
+"""Veritext: Semantic text validation framework for Python."""
+
+__version__ = "0.1.0-dev"
+__all__ = ["__version__"]
diff --git a/src/veritext/core/__init__.py b/src/veritext/core/__init__.py
new file mode 100644
index 0000000..41db193
--- /dev/null
+++ b/src/veritext/core/__init__.py
@@ -0,0 +1,36 @@
+"""Core module: shared types, tokenisation, and configuration."""
+
+from veritext.core.exceptions import (
+    BenchmarkError,
+    ConfigurationError,
+    DependencyError,
+    EmbeddingError,
+    InvalidThresholdError,
+    MetricError,
+    RegressionDetectedError,
+    StorageError,
+    TokenisationError,
+    ValidationError,
+    VeritextError,
+)
+from veritext.core.tokenisation import Tokeniser, WordTokeniser
+from veritext.core.types import CheckResult, ValidationContext, ValidationResult
+
+__all__ = [
+    "BenchmarkError",
+    "CheckResult",
+    "ConfigurationError",
+    "DependencyError",
+    "EmbeddingError",
+    "InvalidThresholdError",
+    "MetricError",
+    "RegressionDetectedError",
+    "StorageError",
+    "TokenisationError",
+    "Tokeniser",
+    "ValidationContext",
+    "ValidationError",
+    "ValidationResult",
+    "VeritextError",
+    "WordTokeniser",
+]
diff --git a/src/veritext/core/exceptions.py b/src/veritext/core/exceptions.py
new file mode 100644
index 0000000..b3aedca
--- /dev/null
+++ b/src/veritext/core/exceptions.py
@@ -0,0 +1,45 @@
+"""Exception hierarchy for Veritext."""
+
+
+class VeritextError(Exception):
+    """Base exception for all Veritext errors."""
+
+
+class MetricError(VeritextError):
+    """Error during metric computation."""
+
+
+class TokenisationError(MetricError):
+    """Error during text tokenisation."""
+
+
+class EmbeddingError(MetricError):
+    """Error computing embeddings (semantic similarity)."""
+
+
+class ValidationError(VeritextError):
+    """Error during validation."""
+
+
+class InvalidThresholdError(ValidationError):
+    """Invalid threshold value provided."""
+
+
+class BenchmarkError(VeritextError):
+    """Error during benchmarking."""
+
+
+class StorageError(BenchmarkError):
+    """Error reading/writing benchmark storage."""
+
+
+class RegressionDetectedError(BenchmarkError):
+    """Quality regression detected (used in CI)."""
+
+
+class ConfigurationError(VeritextError):
+    """Invalid configuration."""
+
+
+class DependencyError(VeritextError):
+    """Optional dependency not installed."""
diff --git a/src/veritext/py.typed b/src/veritext/py.typed
new file mode 100644
index 0000000..e69de29