structflo-ner 0.2.0__tar.gz → 0.2.2__tar.gz

{structflo_ner-0.2.0 → structflo_ner-0.2.2}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
         run: uv python install 3.12
 
       - name: Install dependencies
-        run: uv sync --dev
+        run: uv sync --dev --extra fast --extra dataframe
 
       - name: Lint
         run: uv run ruff check structflo/ tests/

{structflo_ner-0.2.0 → structflo_ner-0.2.2}/PKG-INFO

@@ -1,12 +1,15 @@
 Metadata-Version: 2.4
 Name: structflo-ner
-Version: 0.2.0
+Version: 0.2.2
 Summary: Drug discovery NER wrapper around LangExtract — zero-config entity extraction for chemistry and biology.
 License: Apache-2.0
 Requires-Python: >=3.10
 Requires-Dist: langextract>=1.1.1
 Provides-Extra: dataframe
 Requires-Dist: pandas>=1.5; extra == 'dataframe'
+Provides-Extra: fast
+Requires-Dist: pyyaml>=6.0; extra == 'fast'
+Requires-Dist: rapidfuzz>=3.0; extra == 'fast'
 Description-Content-Type: text/markdown
 
 # structflo.ner

structflo_ner-0.2.2/notebooks/02_fast_ner.ipynb

@@ -0,0 +1,416 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cell-0",
+   "metadata": {},
+   "source": [
+    "# Fast Dictionary-Based NER for TB Drug Discovery\n",
+    "\n",
+    "This notebook demonstrates `FastNERExtractor` — a fast, deterministic NER\n",
+    "engine that uses curated YAML gazetteers instead of an LLM.\n",
+    "\n",
+    "1. Basic usage\n",
+    "2. How matching works (exact, regex, fuzzy)\n",
+    "3. Working with results (same as LLM extractor)\n",
+    "4. Custom gazetteers\n",
+    "5. Adding new entity types\n",
+    "6. Batch extraction & performance"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-1",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "```bash\n",
+    "uv add \"structflo-ner[fast]\"\n",
+    "# for DataFrame support\n",
+    "uv add \"structflo-ner[fast,dataframe]\"\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from structflo.ner.fast import FastNERExtractor"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-3",
+   "metadata": {},
+   "source": [
+    "## 1. Basic Usage\n",
+    "\n",
+    "No API key, no LLM, no network — just instantiate and extract.\n",
+    "The built-in gazetteers cover TB drug discovery entities."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fast = FastNERExtractor()\n",
+    "\n",
+    "text = (\n",
+    "    \"Bedaquiline (TMC207) is a diarylquinoline that inhibits the \"\n",
+    "    \"mycobacterial ATP synthase subunit c encoded by atpE (Rv1305). \"\n",
+    "    \"It shows potent activity against Mycobacterium tuberculosis \"\n",
+    "    \"including MDR-TB and XDR-TB. The compound was identified through \"\n",
+    "    \"whole-cell screening and targets the energy metabolism pathway.\"\n",
+    ")\n",
+    "\n",
+    "result = fast.extract(text)\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-5",
+   "metadata": {},
+   "source": [
+    "## 2. How Matching Works\n",
+    "\n",
+    "The extractor uses a three-phase matching strategy:\n",
+    "\n",
+    "| Phase | Method | What it catches |\n",
+    "|---|---|---|\n",
+    "| 1 | **Exact match** | Case-sensitive and normalized dictionary lookups with word-boundary enforcement |\n",
+    "| 1b | **Regex patterns** | Auto-derived from accession number seeds (Rv tags, UniProt, PDB, etc.) |\n",
+    "| 2 | **Fuzzy match** | Typos and minor variants via rapidfuzz (configurable threshold) |\n",
+    "\n",
+    "Each entity's `attributes` dict includes the `match_method` used."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Inspect match methods\n",
+    "for entity in result.all_entities():\n",
+    "    method = entity.attributes.get(\"match_method\", \"\")\n",
+    "    canonical = entity.attributes.get(\"canonical\", entity.text)\n",
+    "    print(f\"{entity.entity_type:25s} | {entity.text:30s} | method={method:6s} | canonical={canonical}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-7",
+   "metadata": {},
+   "source": [
+    "### Regex matching for accession numbers\n",
+    "\n",
+    "Seed entries in `accession_number.yml` auto-derive regex patterns.\n",
+    "For example, `Rv0005` teaches the system `Rv\\d{4}[c]?`, so *all* Rv locus tags\n",
+    "are matched — not just the ones listed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Rv2043c is NOT in the YAML, but the regex pattern catches it\n",
+    "result2 = fast.extract(\"PptT is encoded by Rv2043c and is essential for mycolic acid biosynthesis.\")\n",
+    "\n",
+    "print(\"Accessions found:\")\n",
+    "for a in result2.accessions:\n",
+    "    print(f\"  {a.text} (method: {a.attributes['match_method']})\")\n",
+    "\n",
+    "print(\"\\nTargets found:\")\n",
+    "for t in result2.targets:\n",
+    "    print(f\"  {t.text}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-9",
+   "metadata": {},
+   "source": [
+    "### Fuzzy matching\n",
+    "\n",
+    "Catches typos and minor spelling variants. The threshold (default 85) controls sensitivity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# \"Bedaquilne\" is a typo for \"Bedaquiline\"\n",
+    "fuzzy_result = fast.extract(\"Bedaquilne showed activity against TB\")\n",
+    "\n",
+    "for c in fuzzy_result.compounds:\n",
+    "    print(f\"Found: {c.text!r} -> canonical: {c.attributes.get('canonical', c.text)!r} (method: {c.attributes['match_method']})\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Disable fuzzy matching for strict mode\n",
+    "strict = FastNERExtractor(fuzzy_threshold=0)\n",
+    "strict_result = strict.extract(\"Bedaquilne showed activity against TB\")\n",
+    "\n",
+    "print(f\"Compounds (strict): {strict_result.compounds}\")  # empty — typo not matched\n",
+    "print(f\"Diseases  (strict): {[d.text for d in strict_result.diseases]}\")  # TB still matched"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-12",
+   "metadata": {},
+   "source": [
+    "## 3. Working with Results\n",
+    "\n",
+    "`FastNERExtractor` returns the same `NERResult` objects as the LLM-based `NERExtractor`.\n",
+    "All downstream tooling works identically."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Typed entity lists\n",
+    "print(\"Compounds:\", [c.text for c in result.compounds])\n",
+    "print(\"Targets:\", [t.text for t in result.targets])\n",
+    "print(\"Diseases:\", [d.text for d in result.diseases])\n",
+    "print(\"Accessions:\", [a.text for a in result.accessions])\n",
+    "print(\"Screening methods:\", [s.text for s in result.screening_methods])\n",
+    "print(\"Products:\", [p.text for p in result.products])\n",
+    "print(\"Functional categories:\", [f.text for f in result.functional_categories])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-14",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Export to DataFrame\n",
+    "df = result.to_dataframe()\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Character offsets let you highlight entities in the source text\n",
+    "for entity in result.all_entities():\n",
+    "    if entity.char_start is not None:\n",
+    "        span = text[entity.char_start:entity.char_end]\n",
+    "        print(f\"[{entity.char_start:3d}:{entity.char_end:3d}] {entity.entity_type:25s} | {span!r}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-16",
+   "metadata": {},
+   "source": [
+    "## 4. Custom Gazetteers\n",
+    "\n",
+    "YAML files contain only names — one per line. The filename becomes the `entity_type`.\n",
+    "\n",
+    "```yaml\n",
+    "# my_gazetteers/target.yml\n",
+    "- MyNovelTarget\n",
+    "- AnotherTarget\n",
+    "- KinaseX\n",
+    "```\n",
+    "\n",
+    "```python\n",
+    "fast = FastNERExtractor(gazetteer_dir=\"my_gazetteers/\")\n",
+    "```\n",
+    "\n",
+    "You can also add terms programmatically without creating files:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Add extra terms on top of the built-in gazetteers\n",
+    "custom = FastNERExtractor(\n",
+    "    extra_gazetteers={\n",
+    "        \"target\": [\"MyNovelTarget\", \"KinaseX\"],\n",
+    "        \"compound_name\": [\"CompoundABC\"],\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "r = custom.extract(\"CompoundABC inhibits MyNovelTarget in M. tuberculosis\")\n",
+    "print(\"Compounds:\", [c.text for c in r.compounds])\n",
+    "print(\"Targets:\", [t.text for t in r.targets])\n",
+    "print(\"Diseases:\", [d.text for d in r.diseases])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-18",
+   "metadata": {},
+   "source": [
+    "## 5. Adding New Entity Types\n",
+    "\n",
+    "To add a new gazetteer, just drop a YAML file into the gazetteers directory.\n",
+    "The filename (without `.yml`) must match an `entity_type` from the entity class map.\n",
+    "\n",
+    "**Built-in entity types:**\n",
+    "\n",
+    "| Filename | entity_type | Python class |\n",
+    "|---|---|---|\n",
+    "| `target.yml` | target | `TargetEntity` |\n",
+    "| `gene_name.yml` | gene_name | `TargetEntity` |\n",
+    "| `compound_name.yml` | compound_name | `ChemicalEntity` |\n",
+    "| `disease.yml` | disease | `DiseaseEntity` |\n",
+    "| `accession_number.yml` | accession_number | `AccessionEntity` |\n",
+    "| `screening_method.yml` | screening_method | `ScreeningMethodEntity` |\n",
+    "| `functional_category.yml` | functional_category | `FunctionalCategoryEntity` |\n",
+    "| `product.yml` | product | `ProductEntity` |\n",
+    "\n",
+    "**What's auto-derived from names:**\n",
+    "- Case variants (InhA, inha, INHA)\n",
+    "- Hyphen-optional forms (DprE-1 ↔ DprE1)\n",
+    "- Period-optional forms (M. tuberculosis ↔ M tuberculosis)\n",
+    "- Greek letter expansion (β-lactam ↔ beta-lactam)\n",
+    "- Regex patterns for accession number seeds (Rv, MT, UniProt, PDB, RefSeq)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# See what gazetteers are loaded by default\n",
+    "from structflo.ner.fast._loader import load_all_gazetteers\n",
+    "\n",
+    "gazetteers = load_all_gazetteers()\n",
+    "for entity_type, terms in gazetteers.items():\n",
+    "    print(f\"{entity_type:25s} | {len(terms):3d} terms | first 5: {terms[:5]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-20",
+   "metadata": {},
+   "source": [
+    "## 6. Batch Extraction & Performance\n",
+    "\n",
+    "The fast extractor processes text in milliseconds — orders of magnitude faster than LLM-based extraction."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-21",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "abstracts = [\n",
+    "    \"Bedaquiline inhibits AtpE (Rv1305) with nanomolar potency against MDR-TB.\",\n",
+    "    \"Delamanid (OPC-67683) is activated by Ddn and targets mycolic acid biosynthesis in M. tuberculosis.\",\n",
+    "    \"Pretomanid (PA-824) requires activation by Ddn (Rv3547) and kills both replicating and non-replicating Mtb.\",\n",
+    "    \"PBTZ169 (Macozinone) inhibits DprE1 (Rv3790), an essential enzyme in cell wall biosynthesis.\",\n",
+    "    \"SQ109 targets MmpL3, a trehalose monomycolate transporter essential for cell wall assembly.\",\n",
+    "    \"Fragment-based screening identified InhA inhibitors that bypass katG-mediated activation.\",\n",
+    "    \"CRISPRi screening revealed QcrB (Rv2196) as a vulnerable target in energy metabolism.\",\n",
+    "    \"Structure-based drug design targeting KasA (Rv2245) yielded novel fatty acid biosynthesis inhibitors.\",\n",
+    "]\n",
+    "\n",
+    "results = fast.extract(abstracts)\n",
+    "\n",
+    "for i, r in enumerate(results):\n",
+    "    entities = r.all_entities()\n",
+    "    print(f\"Abstract {i+1}: {len(entities)} entities — {[e.text for e in entities]}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-22",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%timeit -n 100\n",
+    "# Benchmark: extract from a single abstract\n",
+    "fast.extract(text)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%timeit -n 10\n",
+    "# Benchmark: extract from 8 abstracts\n",
+    "fast.extract(abstracts)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-24",
+   "metadata": {},
+   "source": [
+    "## Comparing Fast vs LLM Extraction\n",
+    "\n",
+    "The fast extractor is ideal as a **first pass** for bulk screening.\n",
+    "Use the LLM extractor for deeper analysis where context and novel entities matter.\n",
+    "\n",
+    "| | `FastNERExtractor` | `NERExtractor` |\n",
+    "|---|---|---|\n",
+    "| Speed | ~1-5ms per abstract | ~2-5s per abstract |\n",
+    "| Novel entities | Only known terms | Discovers new entities |\n",
+    "| Context awareness | None (string matching) | Full contextual understanding |\n",
+    "| Cost | Free (no API calls) | API costs or GPU |\n",
+    "| Setup | Zero config | API key or Ollama |\n",
+    "| Output | `NERResult` | `NERResult` (identical) |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{structflo_ner-0.2.0 → structflo_ner-0.2.2}/pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dataframe = ["pandas>=1.5"]
+fast = ["rapidfuzz>=3.0", "PyYAML>=6.0"]
 
 [dependency-groups]
 dev = [

{structflo_ner-0.2.0 → structflo_ner-0.2.2}/structflo/ner/__init__.py

@@ -49,6 +49,12 @@ from structflo.ner._entities import (
     TargetEntity,
 )
 from structflo.ner.extractor import NERExtractor
+
+try:
+    from structflo.ner.fast import FastNERExtractor
+except ImportError:  # rapidfuzz / PyYAML not installed
+    FastNERExtractor = None  # type: ignore[assignment,misc]
+
 from structflo.ner.profiles import (
     BIOACTIVITY,
     BIOLOGY,
@@ -61,11 +67,12 @@ from structflo.ner.profiles import (
     EntityProfile,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 __all__ = [
-    # Main class
+    # Main classes
     "NERExtractor",
+    "FastNERExtractor",
     # Profile system
     "EntityProfile",
     "FULL",

structflo_ner-0.2.2/structflo/ner/_prompts.py

@@ -0,0 +1,85 @@
+"""Prompt strings for each built-in EntityProfile."""
+
+CHEMISTRY_PROMPT = (
+    "Extract chemical entities from the text. "
+    "Include: compound names (generic names, IUPAC names, code names like 'Compound 5b', "
+    "brand names, and abbreviations), SMILES strings (the exact SMILES notation as written), "
+    "CAS registry numbers (e.g. '50-78-2'), and molecular formulas (e.g. 'C9H8O4'). "
+    "Do not infer or generate SMILES — only extract them if explicitly present in the text."
+)
+
+BIOLOGY_PROMPT = (
+    "Extract biological target entities from the text. "
+    "Include: protein targets (e.g. 'EGFR', 'CDK4/6', 'PD-L1'), gene names (e.g. 'KRAS', 'TP53', "
+    "'BRCA1'), receptor names, enzyme names, and pathway names. "
+    "For each target, capture the gene symbol if mentioned alongside a protein name. "
+    "Capture the organism context if specified (e.g. 'human', 'mouse')."
+)
+
+BIOACTIVITY_PROMPT = (
+    "Extract bioactivity measurements and assay data from the text. "
+    "Include: potency values (IC50, EC50, Ki, Kd, GI50, CC50), selectivity ratios, "
+    "percent inhibition values, and Hill coefficients. "
+    "For each value, capture the numeric value, unit (nM, µM, mM), and measurement type. "
+    "Also extract assay descriptions: cell lines used (e.g. 'HeLa', 'A549'), assay formats "
+    "(e.g. 'cell viability', 'binding assay', 'enzymatic assay'), and organisms."
+)
+
+DISEASE_PROMPT = (
+    "Extract disease names and clinical indications from the text. "
+    "Include: cancer types (e.g. 'non-small cell lung cancer', 'AML', 'NSCLC'), "
+    "non-oncology diseases (e.g. 'type 2 diabetes', 'rheumatoid arthritis'), "
+    "and therapeutic areas (e.g. 'oncology', 'CNS'). "
+    "Capture both full names and abbreviations. "
+    "For each disease, note the therapeutic area if discernible from context."
+)
+
+FULL_PROMPT = (
+    "Extract all drug discovery entities from the text. "
+    "This includes:\n"
+    "- Chemical entities: compound names (generic, IUPAC, code names, brand names), "
+    "SMILES strings (only if explicitly written), CAS numbers, molecular formulas.\n"
+    "- Biological targets: protein names, gene names, receptor names, enzyme names, pathways.\n"
+    "- Bioactivity data: IC50, EC50, Ki, Kd, and other potency/selectivity measurements "
+    "with their numeric values and units.\n"
+    "- Assay information: cell lines, assay formats, experimental organisms.\n"
+    "- Diseases and indications: cancer types, disease names, therapeutic areas.\n"
+    "- Mechanisms of action: binding modes, inhibition types, selectivity descriptions.\n"
+    "Extract only what is explicitly stated; do not infer or generate values."
+)
+
+# ── Tuberculosis early drug discovery prompts ──────────────────────────
+
+TB_PROMPT = (
+    "Extract drug discovery entities from this tuberculosis research text.\n\n"
+    "DISAMBIGUATION RULES:\n"
+    "- Mycobacterial proteins (e.g. ClpC1, DprE1, InhA, AtpE, MmpL3, QcrB) "
+    "are biological targets, NOT compounds.\n"
+    "- Rv locus tags (Rv3790, Rv1484), UniProt IDs (P9WPS1), and PDB codes "
+    "are accession_number, not target or gene_name.\n"
+    "- Enzyme descriptions like 'enoyl-ACP reductase' are product, not target.\n"
+    "- 'cell wall', 'lipid metabolism' are functional_category, not mechanism_of_action.\n"
+    "- 'fragment screening', 'biochemical assay' are screening_method, not assay.\n"
+    "- Use target for proteins in a drug-targeting context, gene_name for loci, "
+    "protein_name for non-drug-target proteins.\n\n"
+    "Extract only what is explicitly stated; do not infer or generate values."
+)
+
+TB_CHEMISTRY_PROMPT = (
+    "Extract chemical entities from this tuberculosis drug discovery text. "
+    "Include compound names, SMILES (only if explicitly written), CAS numbers, "
+    "and molecular formulas. "
+    "Mycobacterial proteins (ClpC1, DprE1, InhA, AtpE, etc.) are NOT compounds. "
+    "Extract only what is explicitly stated; do not infer or generate values."
+)
+
+TB_BIOLOGY_PROMPT = (
+    "Extract biological entities from this tuberculosis research text. "
+    "Use target for proteins in a drug-targeting context, gene_name for loci, "
+    "protein_name for non-drug-target proteins. "
+    "Rv locus tags and UniProt IDs are accession_number. "
+    "Enzyme descriptions (e.g. 'enoyl-ACP reductase') are product. "
+    "Protein functional categories (e.g. 'cell wall', 'lipid metabolism') "
+    "are functional_category. "
+    "Extract only what is explicitly stated; do not infer or generate values."
+)

{structflo_ner-0.2.0 → structflo_ner-0.2.2}/structflo/ner/extractor.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+import logging
+
 import langextract as lx
 
 from structflo.ner._entities import NERResult
 from structflo.ner._mapping import annotated_doc_to_result
 from structflo.ner.profiles import FULL, EntityProfile
 
+logger = logging.getLogger(__name__)
+
 
 class NERExtractor:
     """Extract drug discovery entities from text with zero configuration.
@@ -109,8 +113,53 @@ class NERExtractor:
         return profile.examples + self._extra_examples
 
     def _build_prompt(self, profile: EntityProfile) -> str:
-        """Return the prompt string for the given profile."""
-        return profile.prompt
+        """Return the prompt string for the given profile.
+
+        Appends an explicit schema constraint listing the allowed
+        entity classes.  This is critical for models that don't support
+        structured-output schemas (e.g. Ollama) where
+        ``use_schema_constraints`` has no effect.
+        """
+        classes = ", ".join(profile.entity_classes)
+        constraint = (
+            f"\n\nIMPORTANT — You MUST classify every extraction using "
+            f"ONLY these entity classes: [{classes}]. "
+            f"Do NOT invent new class names. Any extraction_class not in "
+            f"this list is an error."
+        )
+        return profile.prompt + constraint
+
+    @staticmethod
+    def _filter_extractions(
+        doc: lx.data.AnnotatedDocument,
+        allowed_classes: set[str],
+    ) -> lx.data.AnnotatedDocument:
+        """Drop extractions whose class is not in the profile's allowed set.
+
+        Models without schema-constraint support (e.g. Ollama) may invent
+        arbitrary entity classes.  This post-processing step removes those
+        hallucinated classes so they don't pollute the result.
+        """
+        kept: list[lx.data.Extraction] = []
+        for ext in doc.extractions:
+            if ext.extraction_class in allowed_classes:
+                kept.append(ext)
+            else:
+                logger.warning(
+                    "Dropping extraction with unknown class %r (text=%r). Allowed classes: %s",
+                    ext.extraction_class,
+                    ext.extraction_text,
+                    ", ".join(sorted(allowed_classes)),
+                )
+        return lx.data.AnnotatedDocument(
+            text=doc.text,
+            extractions=kept,
+        )
+
+    @property
+    def _is_ollama(self) -> bool:
+        """Return True when routing to an Ollama endpoint."""
+        return self._model_url is not None
 
     def _run_extraction(
         self,
@@ -125,6 +174,13 @@ class NERExtractor:
         kwargs.setdefault("use_schema_constraints", True)
         kwargs.setdefault("show_progress", False)
 
+        # Ollama defaults to num_ctx=2048 which is far too small for
+        # few-shot NER prompts.  Set a sane default so users don't hit
+        # silent truncation.
+        if self._is_ollama:
+            lm_params = kwargs.setdefault("language_model_params", {})
+            lm_params.setdefault("num_ctx", 8192)
+
         result = lx.extract(
             text_or_documents=text,
             prompt_description=prompt,
@@ -136,6 +192,8 @@ class NERExtractor:
         )
 
         # lx.extract returns a list when given a list; we always pass a single string
-        if isinstance(result, list):
-            return result[0]
-        return result
+        doc = result[0] if isinstance(result, list) else result
+
+        # Post-process: drop extractions with hallucinated entity classes
+        allowed = set(profile.entity_classes)
+        return self._filter_extractions(doc, allowed)