feat(medcat-llm-components): CPDT-108 Add llm components

.github/workflows/medcat-llm-components_ci.yml

@@ -0,0 +1,110 @@
+name: medcat-llm-components - CI (test | publish)
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'medcat-llm-components/v*.*.*'  
+  pull_request:
+    paths:
+      - 'medcat-plugins/llm-comps/**'
+      - '.github/workflows/medcat-llm-components**'
+
+permissions:
+  id-token: write
+
+defaults:
+  run:
+    working-directory: ./medcat-plugins/llm-comps
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.10', '3.11', '3.12' ]
+      max-parallel: 4
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv for Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install the project
+        run: |
+          uv sync --all-extras --dev
+          uv run python -m ensurepip
+          uv run python -m pip install --upgrade pip
+          uv run python -m pip install "../../medcat-v2[spacy]"
+      - name: Check types
+        run: |
+          uv run python -m mypy --follow-imports=normal src/medcat_llm_components
+      - name: Ruff linting
+        run: |
+          uv run ruff check src/medcat_llm_components --preview
+      - name: Test
+        run: |
+          uv run python -m pytest tests
+
+  publish-to-test-PyPI:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0        # fetch all history
+          fetch-tags: true      # fetch tags explicitly
+
+      - name: Install uv for Python 3.10
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.10'
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv run python -m ensurepip
+
+      - name: Set timestamp-based dev version
+        run: |
+          TS=$(date -u +"%Y%m%d%H%M%S")
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_MEDCAT_LLM_COMPONENTS=0.2.2.dev${TS}" >> $GITHUB_ENV
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository_url: https://test.pypi.org/legacy/
+          packages_dir: medcat-plugins/llm-comps/dist
+
+  publish-to-PyPI:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: build
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v7
+
+      - name: Install uv for Python 3.10
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.10'
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv run python -m ensurepip
+
+      - name: Build client package
+        run: |
+          uv build
+
+      - name: Publish production distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages_dir: medcat-plugins/llm-comps/dist

medcat-plugins/llm-comps/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel",  "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "medcat_llm_components"
+dynamic = ["version"]
+description = ""
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [
+    { name="Mart Ratas", email="mart.ratas@kcl.ac.uk" }
+]
+requires-python = ">=3.10"
+
+keywords = ["MedCAT"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: Apache Software License"
+]
+
+dependencies = [
+    "medcat>=2.5",
+    "pydantic",
+    "openai~=3.3.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest",
+]
+
+# entry-points to add onto medcat
+[project.entry-points."medcat.plugins"]
+llm_components = "medcat_llm_components"
+
+[project.urls]
+Homepage = "https://github.com/CogStack/cogstack-nlp/tree/main/medcat-plugins/llm-comps"
+Repository = "https://github.com/CogStack/cogstack-nlp/tree/main/medcat-plugins/llm-comps"
+Issues = "https://github.com/CogStack/cogstack-nlp/issues"
+
+[tool.setuptools_scm]
+root = "../.."
+tag_regex = "^medcat-llm-components/v(?P<version>\\d+(?:\\.\\d+)*)(?:[ab]\\d+|rc\\d+)?$"
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+git_describe_command = "git describe --dirty --tags --long --match 'medcat-llm-components/v*'"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"medcat_llm_components" = ["py.typed"]

medcat-plugins/llm-comps/src/medcat_llm_components/__init__.py

@@ -0,0 +1,3 @@
+from .registration import do_registration as __register
+
+__register()

medcat-plugins/llm-comps/src/medcat_llm_components/base.py

@@ -0,0 +1,151 @@
+"""LLM-based entity provider components for MedCAT (proof of concept).
+
+Targets the OpenAI-compatible chat-completions wire format
+(`POST {base_url}/chat/completions`), since that's the lowest common
+denominator for locally-hosted LLM servers - Ollama, vLLM, llama.cpp's
+server, LM Studio, TGI, text-generation-webui - either natively or via
+an OpenAI-compat mode. It also happens to cover hosted providers
+(OpenAI, Groq, Together, OpenRouter, ...) for free, but that's a
+secondary benefit, not the design target.
+
+Layout:
+    LLMConnectionConfig / AbstractLLMEntityComponent
+        - shared: client construction, retries, structured-output
+          negotiation with fallback, response-text cleanup
+    LLMNERConfig / MyLLMNER
+        - NER step (ents=None): freeform CSV prompt + span
+          reconciliation against the doc
+    LLMLinkConfig / MyLLMLinker
+        - linking step (ents given): structured-output-first, since
+          constraining the model to a candidate list is exactly what
+          it's good at
+"""
+# from __future__ import annotations
+
+import logging
+import re
+import time
+from abc import ABC
+from typing import Any
+
+from medcat.components.types import AbstractEntityProvidingComponent
+from medcat.config.config import ComponentConfig
+from openai import APIConnectionError, APIError, APITimeoutError, OpenAI
+
+logger = logging.getLogger(__name__)
+
+
+class UnknownSpanException(ValueError):
+    """Raised when an LLM-reported span can't be reconciled with the source text."""
+
+
+class _StructuredOutputUnsupported(Exception):
+    """Internal signal: backend rejected response_format; retry freeform."""
+
+
+def _looks_like_unsupported_response_format(exc: Exception) -> bool:
+    # NOTE: heuristic. Backends don't agree on a dedicated error type for
+    # "I don't support response_format" - they just 400 with varying
+    # messages. This is best-effort, not a contract; if you hit a backend
+    # that phrases it differently, structured output will look like a
+    # hard failure instead of falling back. Worth tightening once you
+    # know which backends you actually need to support.
+    msg = str(exc).lower()
+    return any(s in msg for s in (
+        "response_format", "json_schema", "unsupported", "not supported"))
+
+
+# ---------------------------------------------------------------------------
+# Shared plumbing
+# ---------------------------------------------------------------------------
+
+class LLMConnectionConfig(ComponentConfig):
+    """Everything needed to talk to an OpenAI-compatible chat endpoint.
+
+    Shared by every LLM-based component regardless of task. Task
+    configs (LLMNERConfig, LLMLinkConfig) inherit from this.
+    """
+    base_url: str
+    api_key: str = "not-needed"  # most local servers ignore it, but the SDK requires a non-empty string
+    model: str
+    timeout: float = 60.0
+    retries: int = 1
+    retry_backoff_seconds: float = 1.0
+    temperature: float = 0.0
+    use_structured_output: bool = True
+
+
+class AbstractLLMEntityComponent(AbstractEntityProvidingComponent, ABC):
+    """Shared connection / chat / cleanup plumbing for LLM-based components.
+
+    Subclasses own the prompt, the (optional) response schema, and
+    turning the model's response into MedCAT entities.
+    """
+
+    def __init__(self, cnf: LLMConnectionConfig) -> None:
+        super().__init__()
+        self.cnf = cnf
+        self._client = OpenAI(base_url=cnf.base_url, api_key=cnf.api_key)
+        # once a backend tells us it doesn't support structured output,
+        # don't keep paying a failed round-trip to rediscover that
+        self._structured_output_supported = cnf.use_structured_output
+
+    def _chat(self, prompt: str, schema: dict[str, Any] | None = None) -> str:
+        """Send `prompt` as a single user message, return the raw text
+        response. `schema`, if given, requests structured output for
+        this call specifically (falls back to freeform if the backend
+        rejects it). Retries transient connection/timeout failures."""
+        use_schema = schema if self._structured_output_supported else None
+
+        last_exc: Exception | None = None
+        for attempt in range(self.cnf.retries + 1):
+            try:
+                return self._one_call(prompt, use_schema)
+            except _StructuredOutputUnsupported:
+                logger.warning(
+                    "%s: backend rejected structured output, falling "
+                    "back to freeform for the rest of this session",
+                    self.cnf.comp_name)
+                self._structured_output_supported = False
+                use_schema = None
+                continue  # retry immediately, don't burn a retry slot on this
+            except (APIConnectionError, APITimeoutError, APIError) as exc:
+                last_exc = exc
+                logger.warning(
+                    "%s: LLM call failed (attempt %d/%d): %s",
+                    self.cnf.comp_name, attempt + 1, self.cnf.retries + 1, exc)
+                if attempt < self.cnf.retries:
+                    time.sleep(self.cnf.retry_backoff_seconds)
+        assert last_exc is not None
+        raise last_exc
+
+    def _one_call(self, prompt: str, schema: dict[str, Any] | None) -> str:
+        kwargs: dict[str, Any] = {
+            "model": self.cnf.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": self.cnf.temperature,
+            "timeout": self.cnf.timeout,
+        }
+        if schema is not None:
+            kwargs["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {"name": "response", "schema": schema, "strict": True},
+            }
+        try:
+            resp = self._client.chat.completions.create(**kwargs)
+        except APIError as exc:
+            if schema is not None and _looks_like_unsupported_response_format(exc):
+                raise _StructuredOutputUnsupported from exc
+            raise
+        return resp.choices[0].message.content or ""
+
+    _FENCE_RE = re.compile(r"^```[a-zA-Z]*\n|\n```$")
+
+    def _clean_response(self, raw: str) -> str:
+        text = raw.strip()
+        # models wrap output in ```csv/```json fences despite instructions not to
+        text = self._FENCE_RE.sub("", text).strip()
+        return text
+
+class MisconfiguredComponentException(ValueError):
+    pass