wassitai 0.2.0__tar.gz

wassitai-0.2.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.2.0
+
+First release published to PyPI, as **`wassitai`**.
+
+### Renamed
+
+- **The distribution and import package are now `wassitai`.** Install with `pip install wassitai`
+  and `import wassitai`. The previous name, `llm_parser`, was never published to PyPI.
+- `llm_parser` remains importable as a **deprecated alias** and emits a `DeprecationWarning`. It
+  forwards every attribute and submodule to `wassitai` — `from llm_parser import Client`,
+  `from llm_parser.llm_parser import LLMParser` and `llm_parser.core.formatter` all resolve to the
+  same objects as their `wassitai.*` counterparts, so pickles, `isinstance` checks and module-level
+  state are shared, not duplicated. The alias is removed in 2.0.
+- **Breaking: the REST API moved from the top-level `api` package to `wassitai.api`.** Run it with
+  `uvicorn wassitai.api.app:app` and import from `wassitai.api.*`. Shipping a top-level `api` module
+  would have squatted a very generic import name in every environment that installed this package.
+
+### Added
+
+- The new engine: `Client` / `parse` / `try_parse` / `render`, `Result` with per-stage diagnostics and
+  a confidence score, and the four extension interfaces (`Provider`, `Strategy`, `SchemaAdapter`,
+  `Stage`).
+- REST API and browser playground (`pip install "wassitai[api]"`).
+- Packaging metadata for publication: long description, license, project URLs and classifiers, plus a
+  `LICENSE` file (MIT, as the README already declared).
+
+### Deprecated
+
+- `LLMParser.ask` — use `Client.generate` / `parse`. Still works, still supports Gemini and
+  HuggingFace, removed in 2.0.
+- The `wassitai.llms.providers.*` classes — new providers are presets or `Provider` implementations
+  under `wassitai/providers/`.
+
+### Upgrading from an `llm_parser` checkout
+
+```bash
+pip uninstall llm_parser     # pip will not replace it: the distribution name changed
+pip install wassitai
+```
+
+Nothing else is required — existing `import llm_parser` code keeps working until 2.0, with a warning.

wassitai-0.2.0/LICENSE

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

wassitai-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# The sdist is what distro packagers and `pip install --no-binary` build from, so
+# it carries the things the wheel has no need for: the changelog, and the test
+# suite that proves the tarball is what it claims to be. `packages.find` still
+# excludes `tests*` from the *installed* set -- shipping them here does not put a
+# top-level `tests` package into anyone's site-packages.
+include CHANGELOG.md
+recursive-include tests *.py
+include tests/README.md
+include pytest.ini

wassitai-0.2.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: wassitai
+Version: 0.2.0
+Summary: Universal structured-generation & LLM-output parsing framework
+Author-email: Abdelaziz Kella <kaa.kella.abdelaziz@gmail.com>, Abdelaziz Kella <a.kella@univ-chlef.dz>
+License: MIT
+Project-URL: Homepage, https://github.com/kaaaziz/wassitai
+Project-URL: Repository, https://github.com/kaaaziz/wassitai
+Project-URL: Issues, https://github.com/kaaaziz/wassitai/issues
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: httpx>=0.24
+Requires-Dist: json_repair>=0.25
+Requires-Dist: xmltodict>=0.13
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.29; extra == "api"
+Requires-Dist: python-multipart>=0.0.9; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# Wassitai
+
+Ask an LLM a question, get back a **validated Python object** — not a string you have to parse.
+
+Wassitai sends your prompt with a schema, picks the best structured-output method the provider
+supports, then extracts, repairs, validates and coerces the reply through a deterministic pipeline.
+If the result still doesn't fit the schema, it re-asks the model. Ships as the importable package
+`wassitai`, with a REST API and a browser playground on top.
+
+```bash
+pip install wassitai            # library
+pip install "wassitai[api]"     # + REST API and playground
+```
+
+Code written against the pre-0.2 name still works: `llm_parser` remains importable as a deprecated
+alias for `wassitai` until 2.0. If you have an old editable install of the `llm_parser` *distribution*,
+run `pip uninstall llm_parser` first — pip won't replace it, and its source tree would keep shadowing
+the alias.
+
+## Features
+
+- 🤖 **Any OpenAI-compatible provider** — Groq, OpenAI, DeepSeek and OpenRouter as presets;
+  Together, xAI, Ollama, vLLM or a local server with just `base_url=` and `model=`
+- 🧱 **Five ways to write a schema** — Pydantic model, `{"field": "type"}` dict, JSON Schema, or a
+  JSON or XML schema string
+- 🔁 **Object, JSON or XML out** — the same validated result, rendered however you need it
+- 📊 **Lists** — ask for `list[Invoice]`, get a list back
+- 🧪 **Repairs before it fails** — lifts JSON out of markdown fences and prose, fixes trailing
+  commas, smart quotes and Python-repr output, then re-asks the model if it still doesn't fit
+- 🔒 **Strict or flexible validation** — exact types for production, coercion while prototyping
+- 💡 **Diagnostics you can act on** — every stage reports what it did, a confidence score falls as
+  repairs accumulate, and errors are a typed tree with fixes in the message
+- 🎯 **Pydantic all the way through** — your model is the schema, the validator and the return type
+- 🌐 **A playground, not just a library** — browser console plus a beginner's guide
+- ✅ **329 tests** — unit, integration and end-to-end, with no network calls
+
+## Python
+
+```python
+from wassitai import Client
+from pydantic import BaseModel
+
+class Invoice(BaseModel):
+    number: str
+    total: float
+
+client = Client.from_provider("groq", api_key="…", model="llama-3.3-70b-versatile")
+invoice = client.generate("Extract the invoice from: …", schema=Invoice)   # -> Invoice
+
+# A list, by asking for a list schema:
+invoices = client.generate("Extract all invoices: …", schema=list[Invoice])
+
+# Never raises — for batch pipelines:
+res = client.try_generate("…", schema=Invoice)     # -> Result[Invoice]
+if res.ok:
+    print(res.value, res.confidence)
+
+# Text you already have, no provider call:
+from wassitai import parse, render
+invoice = parse('{"number": "A1", "total": 9.5}', Invoice)
+text = render(invoice, "json")
+```
+
+A schema can be a Pydantic model, a plain `{"field": "type"}` dict, or a JSON Schema.
+`strict=True` enforces exact types; the default coerces close-enough values (`"3"` → `3`).
+`max_retries` caps how often the model is re-asked (default 1).
+
+## REST API & playground
+
+```bash
+uvicorn wassitai.api.app:app --reload
+```
+
+Playground at `http://localhost:8000/`, beginner's guide at `/static/guide.html`,
+OpenAPI reference at `/docs`.
+
+| Method | Path | Does |
+|---|---|---|
+| `POST` | `/v1/generate` | prompt + schema → validated object |
+| `POST` | `/v1/parse` | text + schema → validated object (no provider call) |
+| `GET` | `/v1/providers` | providers and their capabilities |
+| `GET` | `/health` | liveness |
+
+```bash
+curl -X POST http://localhost:8000/v1/generate \
+  -H "X-Provider-Key: $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"groq","prompt":"Extract the invoice: …",
+       "schema":{"number":"str","total":"float"}}'
+```
+
+Provider keys travel per-request in the `X-Provider-Key` header (or come from `<PROVIDER>_API_KEY`
+on the server) and are never stored, logged, or pre-filled into the browser. Errors map to status
+codes: `422` validation · `401` auth · `429` rate limit · `502` provider · `504` timeout.
+
+## How it works
+
+`generate()` → schema adapter → strategy → provider → **pipeline** → validated object.
+
+- **Strategy** — resolved per provider in order `native` (JSON-schema mode) → `tool_calling` →
+  `prompt_repair`, which is the universal floor and needs nothing from the provider.
+- **Pipeline** — six ordered stages: `normalize → extract → syntax_repair → deserialize →
+  validate → coerce`. Each records a diagnostic, and the confidence score falls as repairs and
+  re-asks accumulate.
+- **Extending** — `Provider`, `Strategy`, `SchemaAdapter` and `Stage` are the four interfaces;
+  most providers need only a preset in `wassitai/providers/__init__.py`.
+
+Errors form one tree under `LLMParserError`: `ConfigurationError` (your bug), `ProviderError`
+(the network/provider's), and `ParseError` (the model's).
+
+## Providers
+
+Built-in presets speak the OpenAI wire format: **groq**, **openai**, **deepseek**, **openrouter**.
+Any other OpenAI-compatible endpoint (Together, xAI, Ollama, vLLM, local) works by passing
+`base_url=` and `model=`. Native adapters for Anthropic, Gemini and Bedrock are planned behind the
+same `Provider` interface.
+
+## Why Wassitai
+
+| | Wassitai | Typical structured-output library |
+|---|---|---|
+| **Providers** | 4 presets, plus any OpenAI-compatible endpoint via `base_url=` | An adapter to write per provider |
+| **Output** | A validated object, or the same data as JSON or XML text | JSON only |
+| **Validation** | Strict *and* flexible, chosen per call | One fixed mode |
+| **On a bad answer** | Repairs it, then re-asks the model | Raises and stops |
+| **When it fails** | Per-stage diagnostics and a confidence score | A single validation error |
+| **Ships a UI** | Playground + beginner's guide | Library only |
+
+### Key differentiators
+
+1. **Dual validation modes** — coerce close-enough values while prototyping, enforce exact types in
+   production, without changing your schema.
+2. **It repairs before it gives up** — malformed JSON is fixed, and a reply that still doesn't fit
+   the schema is sent back to the model rather than thrown at you.
+3. **It tells the truth about what happened** — every stage records a diagnostic, and confidence
+   drops as repairs and re-asks accumulate, so a "valid" object you shouldn't trust is visible.
+4. **Any OpenAI-compatible endpoint** — Together, xAI, Ollama, vLLM or a local server need a URL
+   and a model name, not an adapter.
+5. **JSON *and* XML** — the same validated object renders to either.
+6. **A playground, not just a library** — a browser console that exercises the real REST API, with
+   a guide written for people who have never called an LLM.
+
+### Use cases
+
+- **Development** — flexible validation for rapid prototyping
+- **Production** — strict validation for data integrity
+- **Research** — compare providers and strategies on the same prompt and schema
+- **Education** — plain-language guide and honest error messages
+- **Experimentation** — the playground, with no code to write
+
+## From a checkout
+
+```bash
+pip install -e ".[api,dev]"              # editable install with the API and test deps
+pytest                                   # 329 tests, no network calls
+pytest -m unit                           # or: integration, e2e, provider
+pytest --cov=wassitai --cov-report=html
+```
+
+CI runs the same suite on Python 3.9–3.13, plus `ruff` over the current engine, the REST API and the
+`llm_parser` alias (the pre-0.2 `core/` and `llms/` modules are grandfathered).
+
+## Legacy API (removed in 2.0)
+
+`LLMParser.ask` still works and still supports Gemini and HuggingFace, but is deprecated.
+
+| Old | New |
+|---|---|
+| `LLMParser("groq", api_key=k).ask(q, schema=S, fmt="json")` | `Client.from_provider("groq", api_key=k).generate(q, schema=S)` |
+| `...ask(q, schema=S, many=True)` | `...generate(q, schema=list[S])` |
+| `strict_validation=True` | `generate(..., strict=True)` |
+| need the JSON string back | `render(obj, "json")` |
+
+The Streamlit UI at `ui/app.py` (`streamlit run ui/app.py`) targets this legacy path; the
+playground above is the current one.
+
+## License
+
+MIT.
+
+## Contact
+
+Issues and discussions on [GitHub](https://github.com/kaaaziz/wassitai) ·
+kaa.kella.abdelaziz@gmail.com

wassitai-0.2.0/README.md

@@ -0,0 +1,184 @@
+# Wassitai
+
+Ask an LLM a question, get back a **validated Python object** — not a string you have to parse.
+
+Wassitai sends your prompt with a schema, picks the best structured-output method the provider
+supports, then extracts, repairs, validates and coerces the reply through a deterministic pipeline.
+If the result still doesn't fit the schema, it re-asks the model. Ships as the importable package
+`wassitai`, with a REST API and a browser playground on top.
+
+```bash
+pip install wassitai            # library
+pip install "wassitai[api]"     # + REST API and playground
+```
+
+Code written against the pre-0.2 name still works: `llm_parser` remains importable as a deprecated
+alias for `wassitai` until 2.0. If you have an old editable install of the `llm_parser` *distribution*,
+run `pip uninstall llm_parser` first — pip won't replace it, and its source tree would keep shadowing
+the alias.
+
+## Features
+
+- 🤖 **Any OpenAI-compatible provider** — Groq, OpenAI, DeepSeek and OpenRouter as presets;
+  Together, xAI, Ollama, vLLM or a local server with just `base_url=` and `model=`
+- 🧱 **Five ways to write a schema** — Pydantic model, `{"field": "type"}` dict, JSON Schema, or a
+  JSON or XML schema string
+- 🔁 **Object, JSON or XML out** — the same validated result, rendered however you need it
+- 📊 **Lists** — ask for `list[Invoice]`, get a list back
+- 🧪 **Repairs before it fails** — lifts JSON out of markdown fences and prose, fixes trailing
+  commas, smart quotes and Python-repr output, then re-asks the model if it still doesn't fit
+- 🔒 **Strict or flexible validation** — exact types for production, coercion while prototyping
+- 💡 **Diagnostics you can act on** — every stage reports what it did, a confidence score falls as
+  repairs accumulate, and errors are a typed tree with fixes in the message
+- 🎯 **Pydantic all the way through** — your model is the schema, the validator and the return type
+- 🌐 **A playground, not just a library** — browser console plus a beginner's guide
+- ✅ **329 tests** — unit, integration and end-to-end, with no network calls
+
+## Python
+
+```python
+from wassitai import Client
+from pydantic import BaseModel
+
+class Invoice(BaseModel):
+    number: str
+    total: float
+
+client = Client.from_provider("groq", api_key="…", model="llama-3.3-70b-versatile")
+invoice = client.generate("Extract the invoice from: …", schema=Invoice)   # -> Invoice
+
+# A list, by asking for a list schema:
+invoices = client.generate("Extract all invoices: …", schema=list[Invoice])
+
+# Never raises — for batch pipelines:
+res = client.try_generate("…", schema=Invoice)     # -> Result[Invoice]
+if res.ok:
+    print(res.value, res.confidence)
+
+# Text you already have, no provider call:
+from wassitai import parse, render
+invoice = parse('{"number": "A1", "total": 9.5}', Invoice)
+text = render(invoice, "json")
+```
+
+A schema can be a Pydantic model, a plain `{"field": "type"}` dict, or a JSON Schema.
+`strict=True` enforces exact types; the default coerces close-enough values (`"3"` → `3`).
+`max_retries` caps how often the model is re-asked (default 1).
+
+## REST API & playground
+
+```bash
+uvicorn wassitai.api.app:app --reload
+```
+
+Playground at `http://localhost:8000/`, beginner's guide at `/static/guide.html`,
+OpenAPI reference at `/docs`.
+
+| Method | Path | Does |
+|---|---|---|
+| `POST` | `/v1/generate` | prompt + schema → validated object |
+| `POST` | `/v1/parse` | text + schema → validated object (no provider call) |
+| `GET` | `/v1/providers` | providers and their capabilities |
+| `GET` | `/health` | liveness |
+
+```bash
+curl -X POST http://localhost:8000/v1/generate \
+  -H "X-Provider-Key: $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"groq","prompt":"Extract the invoice: …",
+       "schema":{"number":"str","total":"float"}}'
+```
+
+Provider keys travel per-request in the `X-Provider-Key` header (or come from `<PROVIDER>_API_KEY`
+on the server) and are never stored, logged, or pre-filled into the browser. Errors map to status
+codes: `422` validation · `401` auth · `429` rate limit · `502` provider · `504` timeout.
+
+## How it works
+
+`generate()` → schema adapter → strategy → provider → **pipeline** → validated object.
+
+- **Strategy** — resolved per provider in order `native` (JSON-schema mode) → `tool_calling` →
+  `prompt_repair`, which is the universal floor and needs nothing from the provider.
+- **Pipeline** — six ordered stages: `normalize → extract → syntax_repair → deserialize →
+  validate → coerce`. Each records a diagnostic, and the confidence score falls as repairs and
+  re-asks accumulate.
+- **Extending** — `Provider`, `Strategy`, `SchemaAdapter` and `Stage` are the four interfaces;
+  most providers need only a preset in `wassitai/providers/__init__.py`.
+
+Errors form one tree under `LLMParserError`: `ConfigurationError` (your bug), `ProviderError`
+(the network/provider's), and `ParseError` (the model's).
+
+## Providers
+
+Built-in presets speak the OpenAI wire format: **groq**, **openai**, **deepseek**, **openrouter**.
+Any other OpenAI-compatible endpoint (Together, xAI, Ollama, vLLM, local) works by passing
+`base_url=` and `model=`. Native adapters for Anthropic, Gemini and Bedrock are planned behind the
+same `Provider` interface.
+
+## Why Wassitai
+
+| | Wassitai | Typical structured-output library |
+|---|---|---|
+| **Providers** | 4 presets, plus any OpenAI-compatible endpoint via `base_url=` | An adapter to write per provider |
+| **Output** | A validated object, or the same data as JSON or XML text | JSON only |
+| **Validation** | Strict *and* flexible, chosen per call | One fixed mode |
+| **On a bad answer** | Repairs it, then re-asks the model | Raises and stops |
+| **When it fails** | Per-stage diagnostics and a confidence score | A single validation error |
+| **Ships a UI** | Playground + beginner's guide | Library only |
+
+### Key differentiators
+
+1. **Dual validation modes** — coerce close-enough values while prototyping, enforce exact types in
+   production, without changing your schema.
+2. **It repairs before it gives up** — malformed JSON is fixed, and a reply that still doesn't fit
+   the schema is sent back to the model rather than thrown at you.
+3. **It tells the truth about what happened** — every stage records a diagnostic, and confidence
+   drops as repairs and re-asks accumulate, so a "valid" object you shouldn't trust is visible.
+4. **Any OpenAI-compatible endpoint** — Together, xAI, Ollama, vLLM or a local server need a URL
+   and a model name, not an adapter.
+5. **JSON *and* XML** — the same validated object renders to either.
+6. **A playground, not just a library** — a browser console that exercises the real REST API, with
+   a guide written for people who have never called an LLM.
+
+### Use cases
+
+- **Development** — flexible validation for rapid prototyping
+- **Production** — strict validation for data integrity
+- **Research** — compare providers and strategies on the same prompt and schema
+- **Education** — plain-language guide and honest error messages
+- **Experimentation** — the playground, with no code to write
+
+## From a checkout
+
+```bash
+pip install -e ".[api,dev]"              # editable install with the API and test deps
+pytest                                   # 329 tests, no network calls
+pytest -m unit                           # or: integration, e2e, provider
+pytest --cov=wassitai --cov-report=html
+```
+
+CI runs the same suite on Python 3.9–3.13, plus `ruff` over the current engine, the REST API and the
+`llm_parser` alias (the pre-0.2 `core/` and `llms/` modules are grandfathered).
+
+## Legacy API (removed in 2.0)
+
+`LLMParser.ask` still works and still supports Gemini and HuggingFace, but is deprecated.
+
+| Old | New |
+|---|---|
+| `LLMParser("groq", api_key=k).ask(q, schema=S, fmt="json")` | `Client.from_provider("groq", api_key=k).generate(q, schema=S)` |
+| `...ask(q, schema=S, many=True)` | `...generate(q, schema=list[S])` |
+| `strict_validation=True` | `generate(..., strict=True)` |
+| need the JSON string back | `render(obj, "json")` |
+
+The Streamlit UI at `ui/app.py` (`streamlit run ui/app.py`) targets this legacy path; the
+playground above is the current one.
+
+## License
+
+MIT.
+
+## Contact
+
+Issues and discussions on [GitHub](https://github.com/kaaaziz/wassitai) ·
+kaa.kella.abdelaziz@gmail.com

wassitai-0.2.0/llm_parser/__init__.py

@@ -0,0 +1,116 @@
+"""Deprecated import alias for :mod:`wassitai`.
+
+The distribution was renamed ``llm_parser`` -> ``wassitai`` in 0.2. This package
+exists only so code written against the old name keeps working: it forwards
+every attribute *and* every submodule to :mod:`wassitai`, so both
+
+    from llm_parser import Client, parse
+    from llm_parser.llm_parser import LLMParser
+    from llm_parser.core import formatter
+
+resolve to the very same objects the ``wassitai.*`` paths give you -- not copies.
+It will be removed in 2.0; import from ``wassitai`` instead.
+
+Two deliberate limits, neither of which any caller in this repo relies on:
+``pkgutil.iter_modules(llm_parser.__path__)`` enumerates nothing (this directory
+really is empty), and ``python -m llm_parser.<mod>`` does not work. Use the
+``wassitai`` names for either.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+import warnings
+
+import wassitai as _wassitai
+
+_OLD = "llm_parser"
+_NEW = "wassitai"
+
+
+class _AliasLoader(importlib.abc.Loader):
+    """Loader that hands back an already-imported ``wassitai`` submodule."""
+
+    def __init__(self, real_name: str) -> None:
+        self._real_name = real_name
+        self._real_spec = None
+
+    def create_module(self, spec):
+        real = importlib.import_module(self._real_name)
+        self._real_spec = real.__spec__
+        return real
+
+    def exec_module(self, module) -> None:
+        # The real module was executed under its own name; re-running it would
+        # duplicate its state (registries, module-level singletons) under a
+        # second identity, which is exactly what this alias exists to prevent.
+        #
+        # Undo the one thing the import machinery did to it on the way here:
+        # `_init_module_attrs` overwrites `__spec__` unconditionally, so
+        # importing `llm_parser.core.formatter` would otherwise rename the live
+        # `wassitai.core.formatter` and blank its `submodule_search_locations` --
+        # breaking `reload()` and `importlib.resources` for callers that never
+        # touched the old name. The alias forwards one way only.
+        if self._real_spec is not None:
+            module.__spec__ = self._real_spec
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+    """Maps ``llm_parser.<sub>`` onto ``wassitai.<sub>``."""
+
+    # Duck-typed marker rather than isinstance: re-importing this module (tests
+    # do, to observe the warning) rebinds the class, so an isinstance check
+    # against the fresh class would miss the finder already on sys.meta_path and
+    # stack up a duplicate on every reload.
+    _wassitai_alias_finder = True
+
+    def find_spec(self, fullname, path=None, target=None):
+        if not fullname.startswith(_OLD + "."):
+            return None
+        real_name = _NEW + fullname[len(_OLD) :]
+        try:
+            real = importlib.import_module(real_name)
+        except ModuleNotFoundError as exc:
+            if exc.name != real_name:
+                # The module exists but its *own* imports failed -- a missing
+                # optional dependency, say. Swallowing that would report the
+                # alias as absent and destroy the real cause.
+                raise
+            return None  # genuinely absent: let the machinery raise as usual
+        return importlib.util.spec_from_loader(
+            fullname,
+            _AliasLoader(real_name),
+            is_package=hasattr(real, "__path__"),
+        )
+
+
+# Ahead of the path-based finder, which would otherwise fail to find submodules
+# that no longer live in this (now almost empty) directory.
+if not any(getattr(f, "_wassitai_alias_finder", False) for f in sys.meta_path):
+    sys.meta_path.insert(0, _AliasFinder())
+
+warnings.warn(
+    "The 'llm_parser' package was renamed to 'wassitai'; install it with "
+    "`pip install wassitai` and import `wassitai`. The 'llm_parser' alias will "
+    "be removed in 2.0.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = list(_wassitai.__all__)
+
+
+def __getattr__(name: str):
+    # Delegated rather than star-imported so the alias never drifts from the
+    # real package's surface as that surface grows.
+    try:
+        return getattr(_wassitai, name)
+    except AttributeError:
+        raise AttributeError(f"module {_OLD!r} has no attribute {name!r}") from None
+
+
+def __dir__():
+    return sorted(set(__all__) | set(globals()))