omop-llm 0.1.1__tar.gz

omop_llm-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs 
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types:
+      - completed
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache 
+          restore-keys: |
+            mkdocs-material-
+            
+      - name: Install MkDocs and Plugins
+        run: pip install mkdocs mkdocs-material mkdocstrings-python mkdocs-mermaid2-plugin mkdocs-table-reader-plugin
+        
+      - name: Install omop-llm
+        run: pip install .
+        
+      - name: Deploy Docs
+        run: mkdocs gh-deploy --force

omop_llm-0.1.1/.github/workflows/lint-pr.yml

@@ -0,0 +1,17 @@
+# This workflow runs a linter on pull requests to ensure the right prefix is used for semantic-versioning
+name: "Lint PR"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

omop_llm-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      id-token: write # Required for Trusted Publishing to PyPI
+      contents: write # Required for Semantic Release to push tags/labels
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/omop-llm
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Semantic Release
+        id: semantic
+        uses: cycjimmy/semantic-release-action@v6
+        with:
+          extra_plugins: |
+            @semantic-release/changelog
+            @semantic-release/git
+            @semantic-release/exec
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        if: steps.semantic.outputs.new_release_published == 'true'
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build and publish to PyPI
+        if: steps.semantic.outputs.new_release_published == 'true'
+        run: |
+          uv build
+          uv publish

omop_llm-0.1.1/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

omop_llm-0.1.1/.releaserc.json

@@ -0,0 +1,22 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "sed -i 's/version = \".*\"/version = \"${nextRelease.version}\"/' pyproject.toml"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "pyproject.toml"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

omop_llm-0.1.1/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [0.1.1](https://github.com/AustralianCancerDataNetwork/omop-llm/compare/v0.1.0...v0.1.1) (2026-04-01)
+
+
+### Bug Fixes
+
+* trigger initial 0.x release ([63ce049](https://github.com/AustralianCancerDataNetwork/omop-llm/commit/63ce04934bdb021b903b87dfd452f2e028324bd0))
+
+# 1.0.0 (2026-04-01)
+
+
+### Bug Fixes
+
+* Accurate dependencies for deployment ([5ebdfb2](https://github.com/AustralianCancerDataNetwork/omop-llm/commit/5ebdfb2ba088f2dda9cbd0c554c6f4a52fc119e5))
+* direct deployment to pypi ([33bef1a](https://github.com/AustralianCancerDataNetwork/omop-llm/commit/33bef1a2f63493c0d0e3dd71a40d3f214302150f))
+* include releaserc for semantic versioning ([fe62f2f](https://github.com/AustralianCancerDataNetwork/omop-llm/commit/fe62f2f421e9fda61d13bd7be39b14df9b8b816b))

omop_llm-0.1.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: omop-llm
+Version: 0.1.1
+Summary: LLM interfaces for OMOP
+Author-email: Nico Loesch <n.loesch@unsw.edu.au>
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: instructor>=1.13.0
+Requires-Dist: numpy
+Requires-Dist: openai
+Requires-Dist: prompt-spec>=0.1.4
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# omop-llm
+LLM interface for embedding and instructor tasks. Extended documentation can be found [here](https://AustralianCancerDataNetwork.github.io/omop-llm).

omop_llm-0.1.1/README.md

@@ -0,0 +1,2 @@
+# omop-llm
+LLM interface for embedding and instructor tasks. Extended documentation can be found [here](https://AustralianCancerDataNetwork.github.io/omop-llm).

omop_llm-0.1.1/docs/index.md

@@ -0,0 +1,19 @@
+# OMOP LLM Interface
+
+`omop-llm` is designed as a simple LLM interface in the context of the OMOP CDM. Particularly, the wrapper currently exposes two interfaces:
+
+!!! warning
+
+    The backend is realised as an OpenAI client that would support a wide variety of models but we currently only support Ollama. Extension for this is planned in future releases.
+
+- **`LLMClient`**: Base client with the capacity to:
+    - obtain metadata information
+    - calculate embeddings on demand
+    - calculate semantic similarity
+- **`InstructorClient`**: Child client of `LLMClient` to:
+    - provide an interface for the [`instructor`](https://python.useinstructor.com/) library with easy instantiation.
+    - chat completions using chat messages.
+
+
+## Documentation overview
+- [Installation](usage/installation.md)

omop_llm-0.1.1/docs/reference.md

@@ -0,0 +1,10 @@
+# API Reference
+
+This reference is automatically generated from the source code.
+
+::: omop_llm
+    options:
+      members:
+        - interface
+      show_submodules: true
+      show_root_heading: true

omop_llm-0.1.1/docs/usage/installation.md

@@ -0,0 +1,7 @@
+# Installation instructions
+
+The package is currently only available from GitHub. 
+
+```bash
+pip install git+https://github.com/AustralianCancerDataNetwork/omop-llm.git
+```

omop_llm-0.1.1/mkdocs.yml

@@ -0,0 +1,51 @@
+site_name: OMOP LLM
+site_description: LLM interface for the OMOP Graph project for easy LLM tooling.
+site_url: https://AustralianCancerDataNetwork.github.io/omop-llm
+repo_url: https://github.com/AustralianCancerDataNetwork/omop-llm
+repo_name: omop-llm
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - content.code.copy
+    - content.code.annotate
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: light-blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Installation: usage/installation.md
+  - "API Reference": reference.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: numpy
+            show_root_heading: true
+            show_source: false
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - tables

omop_llm-0.1.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "omop-llm"
+version = "0.1.1"
+description = "LLM interfaces for OMOP"
+authors = [
+  {name = "Nico Loesch", email = "n.loesch@unsw.edu.au"}
+]
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "instructor>=1.13.0",
+    "prompt-spec>=0.1.4",
+    "openai",
+    "numpy",
+    "pydantic",
+  ]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "types-pyyaml>=6.0.12.20250915",
+    "mkdocs<2.0",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "mkdocs-mermaid2-plugin"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omop_llm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+markers = [
+  "unit: Unit tests that do not require external API calls",
+  "integration: Tests that hit live LLM endpoints (requires API keys)",
+]

omop_llm-0.1.1/src/omop_llm/__init__.py

@@ -0,0 +1,3 @@
+from .interface import LLMClient, InstructorClient, CHAT_MESSAGE_DICT
+
+__all__ = ["LLMClient", "InstructorClient", "CHAT_MESSAGE_DICT"]

omop_llm-0.1.1/src/omop_llm/interface/__init__.py

@@ -0,0 +1,2 @@
+from .client import LLMClient, CHAT_MESSAGE_DICT
+from .instructor_client import InstructorClient

omop_llm-0.1.1/src/omop_llm/interface/client.py

@@ -0,0 +1,277 @@
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union, TypeAlias, Tuple
+
+import numpy as np
+import requests
+from openai import OpenAI
+
+logger = logging.getLogger(__name__)
+
+
+CHAT_MESSAGE_DICT: TypeAlias = Dict[str, str]
+
+
+class LLMClientError(RuntimeError):
+    """
+    Custom exception for LLM Client runtime errors.
+    """
+    pass
+
+
+@dataclass
+class LLMClient:
+    """
+    Base class for LLM clients.
+
+    This class replicates the API of the OntoGPT LLMClient but serves as a
+    base for other implementations (e.g., InstructorClient). Relies on the
+    OpenAI client for core functionality.
+
+    Parameters
+    ----------
+    model : str
+        The name of the model to use (e.g., 'gpt-4', 'llama3').
+    api_base : str
+        The base URL for the API endpoint.
+    api_key : str
+        The API key for authentication.
+    temperature : float, optional
+        The temperature parameter for generation. Default is 1.0.
+    system_message : str, optional
+        The default system message to prepend to chats. Default is "".
+
+    Attributes
+    ----------
+    _base_client : OpenAI
+        The initialized OpenAI client instance.
+    _embedding_dim : int or None
+        Cached embedding dimension size.
+    """
+
+    model: str
+    api_base: str
+    api_key: str = "ollama"  # required by OpenAI client, ignored by Ollama
+    temperature: float = 1.0
+    system_message: str = ""
+    embedding_batch_size: int = 32
+    _base_client: OpenAI = field(init=False, repr=False)
+    _embedding_dim: Optional[int] = field(init=False, default=None)
+
+    def __post_init__(self) -> None:
+        logger.info(f"Initialising {self.__class__.__name__} for model={self.model}")
+        if self.api_key is None:
+            self.api_key = "ollama"  # Default to "ollama" for compatibility, but can be overridden
+
+        self._base_client = OpenAI(
+            base_url=self.api_base,
+            api_key=self.api_key,
+        )
+
+    @property
+    def embedding_dim(self) -> int:
+        """
+        Retrieve the embedding dimension for the current model.
+
+        If the dimension is not cached, it attempts to fetch it from the API.
+        Currently supports Ollama endpoints.
+
+        Returns
+        -------
+        int
+            The size of the embedding vector.
+
+        Raises
+        ------
+        ValueError
+            If model information cannot be found in the Ollama response.
+        NotImplementedError
+            If the API base is not supported for automatic dimension retrieval.
+        """
+        if self._embedding_dim is not None:
+            return self._embedding_dim
+        
+        if (
+            "ollama" in self.api_base or 
+            (
+                (
+                    "localhost" in self.api_base or
+                    "127.0.0.1" in self.api_base
+                ) and self.api_key == "ollama"
+            )
+        ):
+            # Strip /v1 to access base Ollama API
+            ollama_url_without_v1 = self.api_base.replace("/v1", "")
+            requests_url = f"{ollama_url_without_v1}/api/show"
+            
+            response = requests.post(requests_url, json={"name": self.model}).json()
+            model_info = response.get("model_info", {})
+            
+            if model_info:
+                # Find keys resembling 'embedding_length'
+                embedding_key = [key for key in model_info.keys() if "embedding_length" in key]
+                if len(embedding_key) == 1:
+                    self._embedding_dim = int(model_info[embedding_key[0]])
+                    return self._embedding_dim
+            
+            raise ValueError(f"Model information not found in Ollama response: {response}")
+        else:
+            raise NotImplementedError("Embedding dimension retrieval not implemented for this API base")
+
+    @property
+    def base_client(self) -> OpenAI:
+        return self._base_client
+
+    def embeddings(self, text: Union[str, List[str], Tuple[str, ...]], batch_size: Optional[int] = None) -> np.ndarray:
+        """
+        Retrieve embeddings for the given text.
+
+        Parameters
+        ----------
+        text : str or List[str]
+            The input text or list of texts to embed.
+        batch_size : int, optional
+            The number of texts to process in a single API call. Default is 32.
+
+        Returns
+        -------
+        np.ndarray
+            A 2D numpy array containing the embeddings.
+
+        Raises
+        ------
+        AssertionError
+            If the base client has not been initialized.
+        """
+        assert self.base_client is not None, "Base client should be initialized"
+        if batch_size is None:
+            batch_size = self.embedding_batch_size
+        
+        if isinstance(text, str):
+            text = (text, )
+        elif isinstance(text, list):
+            text = tuple(text)
+
+        batch_buffer = []
+
+        for batch_chunk_idx in range(0, len(text), batch_size):
+            logger.debug(f"Processing batch chunk from index {batch_chunk_idx} to {batch_chunk_idx + batch_size}")
+            batch_chunk = text[batch_chunk_idx:batch_chunk_idx + batch_size]
+            response = self.base_client.embeddings.create(
+                model=self.model,
+                input=batch_chunk,
+            )
+            batch_buffer.extend([emb.embedding for emb in response.data])
+
+        return np.array(batch_buffer)
+
+    def similarity(
+        self,
+        terms: Union[str, List[str], np.ndarray],
+        terms_to_match: Union[str, List[str], np.ndarray],
+        **kwargs: Any
+    ) -> np.ndarray:
+        """
+        Calculate the cosine similarity between two sets of terms.
+
+        This method handles inputs as strings, lists of strings, or pre-computed
+        numpy arrays of embeddings.
+
+        Parameters
+        ----------
+        terms : str, List[str], or np.ndarray
+            The source terms or embeddings.
+        terms_to_match : str, List[str], or np.ndarray
+            The target terms or embeddings to match against.
+        **kwargs : Any
+            Additional arguments passed to the embedding function if embedding is required.
+
+        Returns
+        -------
+        np.ndarray
+            A similarity matrix.
+
+        Raises
+        ------
+        ValueError
+            If inputs are not strings, lists, or numpy arrays.
+        """
+        if isinstance(terms, str):
+            terms = [terms]
+        if isinstance(terms_to_match, str):
+            terms_to_match = [terms_to_match]
+
+        # Process source terms
+        if isinstance(terms, list):
+            terms_embeddings = self.embeddings(text=terms, **kwargs)
+        elif isinstance(terms, np.ndarray):
+            terms_embeddings = terms
+        else:
+            raise ValueError("terms must be either a string, list of strings, or numpy array")
+
+        # Process target terms
+        if isinstance(terms_to_match, list):
+            terms_to_match_embeddings = self.embeddings(text=terms_to_match, **kwargs)
+        elif isinstance(terms_to_match, np.ndarray):
+            terms_to_match_embeddings = terms_to_match
+        else:
+            raise ValueError("terms_to_match must be either a string, list of strings, or numpy array")
+
+        return self.cosine_similarity(terms_embeddings, terms_to_match_embeddings)
+
+    @staticmethod
+    def cosine_similarity(vecs_a: np.ndarray, vecs_b: np.ndarray) -> np.ndarray:
+        """
+        Compute the cosine similarity between two matrices of vectors.
+
+        Parameters
+        ----------
+        vecs_a : np.ndarray
+            A 2D array of vectors (Shape: M x D).
+        vecs_b : np.ndarray
+            A 2D array of vectors (Shape: N x D).
+
+        Returns
+        -------
+        np.ndarray
+            The dot product of the normalized vectors (Shape: M x N).
+
+        Notes
+        -----
+        A small epsilon (1e-10) is added to the norms to prevent division by zero.
+        """
+        assert vecs_a.ndim == 2 and vecs_b.ndim == 2, "Input vectors must be 2D arrays"
+        
+        norm_a = np.linalg.norm(vecs_a, axis=1, keepdims=True)
+        norm_b = np.linalg.norm(vecs_b, axis=1, keepdims=True)
+
+        # Prevent division by zero
+        norm_a[norm_a == 0] = 1e-10
+        norm_b[norm_b == 0] = 1e-10
+
+        vecs_a_norm = vecs_a / norm_a
+        vecs_b_norm = vecs_b / norm_b
+
+        return np.dot(vecs_a_norm, vecs_b_norm.T)
+
+    def euclidean_distance(self, text1: str, text2: str, **kwargs: Any) -> float:
+        """
+        Calculate the Euclidean distance between embeddings of two texts.
+
+        Parameters
+        ----------
+        text1 : str
+            The first text string.
+        text2 : str
+            The second text string.
+        **kwargs : Any
+            Additional arguments passed to the embedding function.
+
+        Returns
+        -------
+        float
+            The Euclidean distance (L2 norm) between the two embedding vectors.
+        """
+        a1 = self.embeddings(text1, **kwargs)
+        a2 = self.embeddings(text2, **kwargs)
+        return float(np.linalg.norm(np.array(a1) - np.array(a2)))

omop_llm-0.1.1/src/omop_llm/interface/instructor_client.py

@@ -0,0 +1,153 @@
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union, TypeAlias
+
+import instructor
+from pydantic import BaseModel
+from prompt_spec import PromptTemplate
+
+from .client import LLMClient, LLMClientError
+
+logger = logging.getLogger(__name__)
+
+
+CHAT_MESSAGE_DICT: TypeAlias = Dict[str, str]
+
+
+@dataclass
+class InstructorClient(LLMClient):
+    """
+    LLMClient implementation backed by pydantic-instructor.
+
+    This client extends the base LLMClient to support structured outputs
+    via the `instructor` library.
+
+    Parameters
+    ----------
+    instructor_mode : instructor.Mode
+        The mode for the instructor client (e.g., JSON, TOOLS). Default is JSON.
+
+    Attributes
+    ----------
+    _client : Any
+        The initialized instructor client wrapper.
+    """
+
+    instructor_mode: instructor.Mode = instructor.Mode.JSON
+    _client: Any = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """
+        Initialize the Instructor wrapper around the OpenAI client.
+        """
+        super().__post_init__()
+        self._client = instructor.from_openai(
+            self.base_client,
+            mode=self.instructor_mode,
+        )
+
+    def complete[T: BaseModel](
+        self,
+        messages: List[CHAT_MESSAGE_DICT],
+        response_model: Optional[type[T]] = None,
+        show_prompt: bool = False,
+        **kwargs: Any,
+    ) -> Union[str, T]:
+        """
+        Run a chat completion.
+
+        If `response_model` is provided, structured output is returned based
+        on the Pydantic model. Otherwise, plain text is returned.
+
+        Parameters
+        ----------
+        messages : list of dict
+            The list of chat messages (e.g., `[{'role': 'user', 'content': '...'}]`).
+        response_model : type[T], optional
+            A Pydantic model class (T) to structure the response.
+            Must be a subclass of BaseModel.
+        show_prompt : bool, optional
+            If True, logs the rendered prompt before sending. Default is False.
+        **kwargs : Any
+            Additional arguments passed to `chat.completions.create`.
+
+        Returns
+        -------
+        Union[str, T]
+            The response string (if no model provided) or an instance of T (the Pydantic model).
+
+        Raises
+        ------
+        LLMClientError
+            If the completion request fails.
+        """
+        if show_prompt:
+            # Note: render_prompt_messages only uses the 'messages' list.
+            rendered_text = self.render_prompt_messages(messages=messages)
+            logger.info(f"SENDING PROMPT:\n{rendered_text}")
+
+        try:
+            result = self._client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                temperature=self.temperature,
+                response_model=response_model,
+                **kwargs,
+            )
+        except Exception as e:
+            logger.error(f"Instructor completion failed: {e}")
+            raise LLMClientError("Instructor completion failed") from e
+
+        if response_model is not None:
+            # result is already an instance of T here
+            return result
+
+        return result.choices[0].message.content
+
+    # TODO: The next two messages should be in prompt_spec!
+    def messages_from_prompt_template(
+        self, prompt_template: Optional[PromptTemplate], text: str
+    ) -> List[Dict[str, str]]:
+        """
+        Generate a list of messages from a PromptTemplate.
+
+        Raises
+        ------
+        NotImplementedError
+            This method is currently dropped for Template in LinkML.
+        """
+        raise NotImplementedError("Method dropped for Template in LinkML")
+        
+        # Unreachable code preserved for reference/future implementation
+        # messages = [{"role": "system", "content": prompt_template.system}] if self.system_message else []
+        # for example in prompt_template.examples:
+        #     messages.append({"role": "user", "content": example.input})
+        #     messages.append({"role": "assistant", "content": example.output.model_dump_json(indent=2)})
+        # messages.append({"role": "user", "content": text})
+        # return messages
+
+    def render_prompt_messages(self, messages: List[CHAT_MESSAGE_DICT]) -> str:
+        """
+        Render a list of chat messages into a single string for logging or display.
+
+        Parameters
+        ----------
+        messages : list of dict
+            The chat history.
+
+        Returns
+        -------
+        str
+            A formatted string representation of the conversation.
+        """
+        lines = []
+        for msg in messages:
+            role_label = "System:"
+            if msg['role'] == "user":
+                role_label = "Input:"
+            elif msg['role'] == "assistant":
+                role_label = "Output:"
+            
+            lines.append(f"{role_label} {msg['content']}")
+            
+        return "\n".join(lines)

omop_llm-0.1.1/tests/test_dummy.py

@@ -0,0 +1,4 @@
+def test_import():
+    """Dummy test to ensure the package can be imported."""
+    import omop_llm
+    assert True