nthlayer-common 0.1.0__tar.gz

nthlayer_common-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: nthlayer-common
+Version: 0.1.0
+Summary: Shared utilities for the NthLayer ecosystem
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"

nthlayer_common-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nthlayer-common"
+version = "0.1.0"
+description = "Shared utilities for the NthLayer ecosystem"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nthlayer_common-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nthlayer_common-0.1.0/src/nthlayer_common/__init__.py

@@ -0,0 +1,4 @@
+from nthlayer_common.llm import LLMError, LLMResponse, llm_call
+from nthlayer_common.parsing import clamp, strip_markdown_fences
+
+__all__ = ["llm_call", "LLMResponse", "LLMError", "strip_markdown_fences", "clamp"]

nthlayer_common-0.1.0/src/nthlayer_common/llm.py

@@ -0,0 +1,234 @@
+"""
+Unified LLM interface for NthLayer agentic components.
+
+Two API formats cover the entire market:
+- Anthropic Messages API (Anthropic only)
+- OpenAI Chat Completions API (everyone else)
+
+No third-party LLM libraries. No LiteLLM.
+
+Usage:
+    from nthlayer_common.llm import llm_call
+
+    response = llm_call(
+        system="You are a triage agent...",
+        user="Evaluate this incident...",
+    )
+
+Configuration via environment:
+    NTHLAYER_MODEL          - provider/model (default: anthropic/claude-sonnet-4-20250514)
+    NTHLAYER_LLM_TIMEOUT    - seconds (default: 60)
+    ANTHROPIC_API_KEY       - for anthropic/* models
+    OPENAI_API_KEY          - for openai/*, together/*, groq/*, mistral/*, azure/* models
+    OPENAI_API_BASE         - override endpoint URL for any provider
+    AZURE_OPENAI_ENDPOINT   - Azure OpenAI resource URL
+"""
+
+import os
+import json
+import httpx
+from dataclasses import dataclass
+
+DEFAULT_MODEL = os.environ.get("NTHLAYER_MODEL", "anthropic/claude-sonnet-4-20250514")
+try:
+    TIMEOUT = int(os.environ.get("NTHLAYER_LLM_TIMEOUT", "60"))
+except (ValueError, TypeError):
+    TIMEOUT = 60
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM call."""
+    text: str           # The response content
+    model: str          # Model that was used
+    provider: str       # Provider that was used
+    input_tokens: int | None = None   # Token count for input (if available)
+    output_tokens: int | None = None  # Token count for output (if available)
+
+
+class LLMError(Exception):
+    """Raised when an LLM call fails."""
+    def __init__(self, message: str, provider: str, model: str, cause: Exception | None = None):
+        self.provider = provider
+        self.model = model
+        self.cause = cause
+        super().__init__(f"[{provider}/{model}] {message}")
+
+
+def llm_call(
+    system: str,
+    user: str,
+    model: str | None = None,
+    max_tokens: int = 2000,
+    timeout: int | None = None,
+) -> LLMResponse:
+    """
+    Unified LLM call for all NthLayer agentic components.
+
+    Model format: "provider/model-name"
+      - anthropic/claude-sonnet-4-20250514
+      - openai/gpt-4o
+      - ollama/llama3.1
+      - azure/my-deployment
+      - together/meta-llama/Llama-3-70b
+      - groq/llama-3.1-70b-versatile
+      - mistral/mistral-large-latest
+      - vllm/my-model
+      - lmstudio/my-model
+      - custom/my-model (with OPENAI_API_BASE set)
+
+    Provider determines the API format and endpoint:
+      - "anthropic/*"  -> Anthropic Messages API
+      - Everything else -> OpenAI-compatible Chat Completions API
+
+    Returns LLMResponse with the text content, model, and provider.
+    Raises LLMError on failure with provider/model context.
+
+    Note: callers that wrap llm_call() in asyncio.wait_for(timeout=T) should
+    use the same timeout value. httpx fires the network timeout first; the
+    asyncio.wait_for is a safety net for thread scheduling delays.
+    """
+    model = model or DEFAULT_MODEL
+    _timeout = timeout if timeout is not None else TIMEOUT
+
+    # Parse provider from model string
+    if "/" in model:
+        provider, _, model_name = model.partition("/")
+    else:
+        # Bare model name - guess provider from known prefixes
+        provider = _guess_provider(model)
+        model_name = model
+
+    try:
+        if provider == "anthropic":
+            text, in_tok, out_tok = _call_anthropic(system, user, model_name, max_tokens, _timeout)
+        else:
+            text, in_tok, out_tok = _call_openai_compat(system, user, model_name, provider, max_tokens, _timeout)
+
+        return LLMResponse(
+            text=text, model=model_name, provider=provider,
+            input_tokens=in_tok, output_tokens=out_tok,
+        )
+
+    except httpx.HTTPStatusError as e:
+        raise LLMError(
+            f"HTTP {e.response.status_code}: {e.response.text[:200]}",
+            provider, model_name, e,
+        ) from e
+    except httpx.TimeoutException as e:
+        raise LLMError(
+            f"Timeout after {_timeout}s",
+            provider, model_name, e,
+        ) from e
+    except Exception as e:
+        if isinstance(e, LLMError):
+            raise
+        raise LLMError(str(e), provider, model_name, e) from e
+
+
+def _call_anthropic(system: str, user: str, model: str, max_tokens: int, timeout: int) -> tuple[str, int | None, int | None]:
+    """Call Anthropic Messages API."""
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise LLMError("ANTHROPIC_API_KEY not set", "anthropic", model)
+
+    response = httpx.post(
+        "https://api.anthropic.com/v1/messages",
+        headers={
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        },
+        json={
+            "model": model,
+            "max_tokens": max_tokens,
+            "system": system,
+            "messages": [{"role": "user", "content": user}],
+        },
+        timeout=timeout,
+    )
+    response.raise_for_status()
+    data = response.json()
+    content = data.get("content", [])
+    if not content:
+        raise LLMError("Model returned empty content", "anthropic", model)
+    text = content[0].get("text", "")
+    usage = data.get("usage", {})
+    return text, usage.get("input_tokens"), usage.get("output_tokens")
+
+
+def _call_openai_compat(
+    system: str, user: str, model: str, provider: str, max_tokens: int, timeout: int
+) -> tuple[str, int | None, int | None]:
+    """
+    Call OpenAI-compatible Chat Completions API.
+
+    Works with: OpenAI, Azure OpenAI, Ollama, vLLM, Together AI,
+    Groq, Mistral, LM Studio, any OpenAI-compatible server.
+    """
+    base_url = os.environ.get("OPENAI_API_BASE") or _default_base_url(provider)
+    if not base_url and provider == "azure":
+        raise LLMError("AZURE_OPENAI_ENDPOINT not set", "azure", model)
+    api_key = os.environ.get("OPENAI_API_KEY", "not-needed")  # Ollama/vLLM don't require keys
+
+    # Azure uses api-key header; everything else uses Bearer token
+    if provider == "azure":
+        headers = {
+            "api-key": api_key,
+            "content-type": "application/json",
+        }
+        url = f"{base_url}/{model}/chat/completions?api-version=2024-02-01"
+    else:
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "content-type": "application/json",
+        }
+        url = f"{base_url}/chat/completions"
+
+    response = httpx.post(
+        url,
+        headers=headers,
+        json={
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+        },
+        timeout=timeout,
+    )
+    response.raise_for_status()
+    data = response.json()
+    choices = data.get("choices", [])
+    if not choices:
+        raise LLMError("Model returned empty choices", provider, model)
+    text = (choices[0].get("message") or {}).get("content", "")
+    usage = data.get("usage", {})
+    return text, usage.get("prompt_tokens"), usage.get("completion_tokens")
+
+
+def _default_base_url(provider: str) -> str:
+    """Default API base URLs by provider."""
+    defaults = {
+        "openai": "https://api.openai.com/v1",
+        "ollama": "http://localhost:11434/v1",
+        "vllm": "http://localhost:8000/v1",
+        "lmstudio": "http://localhost:1234/v1",
+        "together": "https://api.together.xyz/v1",
+        "groq": "https://api.groq.com/openai/v1",
+        "mistral": "https://api.mistral.ai/v1",
+        "azure": os.environ.get("AZURE_OPENAI_ENDPOINT", ""),
+    }
+    return defaults.get(provider, "https://api.openai.com/v1")
+
+
+def _guess_provider(model: str) -> str:
+    """Guess provider from bare model name."""
+    if model.startswith("claude"):
+        return "anthropic"
+    if model.startswith("gpt") or model.startswith("o1") or model.startswith("o3"):
+        return "openai"
+    if model.startswith("llama") or model.startswith("mistral") or model.startswith("gemma"):
+        return "ollama"
+    return "openai"  # Default: assume OpenAI-compatible

nthlayer_common-0.1.0/src/nthlayer_common/parsing.py

@@ -0,0 +1,26 @@
+"""Shared parsing utilities for LLM responses.
+
+Used by every component that calls llm_call() and parses the response.
+"""
+from __future__ import annotations
+
+
+def strip_markdown_fences(text: str) -> str:
+    """Strip markdown code fences from model response text.
+
+    Handles ```json, ```, and bare ``` patterns.
+    """
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.split("\n")
+        if lines[0].strip().startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines)
+    return text
+
+
+def clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
+    """Clamp a value to [low, high]. Default: [0.0, 1.0]."""
+    return max(low, min(high, value))

nthlayer_common-0.1.0/src/nthlayer_common.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: nthlayer-common
+Version: 0.1.0
+Summary: Shared utilities for the NthLayer ecosystem
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"

nthlayer_common-0.1.0/src/nthlayer_common.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+src/nthlayer_common/__init__.py
+src/nthlayer_common/llm.py
+src/nthlayer_common/parsing.py
+src/nthlayer_common.egg-info/PKG-INFO
+src/nthlayer_common.egg-info/SOURCES.txt
+src/nthlayer_common.egg-info/dependency_links.txt
+src/nthlayer_common.egg-info/requires.txt
+src/nthlayer_common.egg-info/top_level.txt
+tests/test_llm.py

nthlayer_common-0.1.0/src/nthlayer_common.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nthlayer_common-0.1.0/src/nthlayer_common.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx>=0.27
+
+[dev]
+pytest>=8.0
+ruff>=0.8

nthlayer_common-0.1.0/src/nthlayer_common.egg-info/top_level.txt

@@ -0,0 +1 @@
+nthlayer_common

nthlayer_common-0.1.0/tests/test_llm.py

@@ -0,0 +1,183 @@
+# tests/test_llm.py
+"""Unit tests for the unified LLM wrapper."""
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from nthlayer_common.llm import (
+    LLMError,
+    LLMResponse,
+    _guess_provider,
+    llm_call,
+)
+
+
+def _mock_response(body: dict, status_code: int = 200) -> httpx.Response:
+    """Build a mock httpx.Response."""
+    resp = httpx.Response(
+        status_code=status_code,
+        json=body,
+        request=httpx.Request("POST", "https://mock"),
+    )
+    return resp
+
+
+class TestAnthropicPath:
+    def test_successful_call(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")
+        mock_resp = _mock_response({
+            "content": [{"text": "hello from claude"}],
+            "usage": {"input_tokens": 100, "output_tokens": 50},
+        })
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp) as mock_post:
+            result = llm_call("system", "user", model="anthropic/claude-sonnet-4-20250514")
+
+        assert result.text == "hello from claude"
+        assert result.provider == "anthropic"
+        assert result.model == "claude-sonnet-4-20250514"
+
+        call_args = mock_post.call_args
+        assert "api.anthropic.com/v1/messages" in call_args.args[0]
+        assert call_args.kwargs["headers"]["x-api-key"] == "sk-ant-test"
+        assert call_args.kwargs["headers"]["anthropic-version"] == "2023-06-01"
+
+
+class TestOpenAIPath:
+    def test_successful_call(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        mock_resp = _mock_response({
+            "choices": [{"message": {"content": "hello from gpt"}}],
+            "usage": {"prompt_tokens": 80, "completion_tokens": 40},
+        })
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp) as mock_post:
+            result = llm_call("system", "user", model="openai/gpt-4o")
+
+        assert result.text == "hello from gpt"
+        assert result.provider == "openai"
+        assert result.model == "gpt-4o"
+
+        call_args = mock_post.call_args
+        assert "api.openai.com/v1/chat/completions" in call_args.args[0]
+        assert "Bearer sk-test" in call_args.kwargs["headers"]["Authorization"]
+
+
+class TestOllamaPath:
+    def test_correct_url(self, monkeypatch):
+        monkeypatch.delenv("OPENAI_API_BASE", raising=False)
+        mock_resp = _mock_response({"choices": [{"message": {"content": "local response"}}]})
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp) as mock_post:
+            result = llm_call("system", "user", model="ollama/llama3.1")
+
+        call_args = mock_post.call_args
+        assert "localhost:11434/v1/chat/completions" in call_args.args[0]
+        assert result.provider == "ollama"
+
+
+class TestCustomBaseURL:
+    def test_openai_api_base_override(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_BASE", "http://custom:1234/v1")
+        mock_resp = _mock_response({"choices": [{"message": {"content": "custom"}}]})
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp) as mock_post:
+            result = llm_call("system", "user", model="custom/my-model")
+
+        call_args = mock_post.call_args
+        assert "http://custom:1234/v1/chat/completions" == call_args.args[0]
+
+
+class TestMissingAPIKey:
+    def test_anthropic_no_key_raises(self, monkeypatch):
+        monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+
+        with pytest.raises(LLMError, match="ANTHROPIC_API_KEY not set"):
+            llm_call("system", "user", model="anthropic/claude-sonnet-4-20250514")
+
+
+class TestTimeout:
+    def test_timeout_raises_llm_error(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")
+
+        with patch("nthlayer_common.llm.httpx.post", side_effect=httpx.TimeoutException("timed out")):
+            with pytest.raises(LLMError, match="Timeout"):
+                llm_call("system", "user", model="anthropic/claude-sonnet-4-20250514", timeout=5)
+
+
+class TestHTTPError:
+    def test_429_raises_llm_error(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        resp = httpx.Response(
+            status_code=429,
+            text="Rate limit exceeded",
+            request=httpx.Request("POST", "https://api.openai.com/v1/chat/completions"),
+        )
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=resp):
+            with pytest.raises(LLMError, match="HTTP 429"):
+                llm_call("system", "user", model="openai/gpt-4o")
+
+
+class TestGuessProvider:
+    def test_claude_is_anthropic(self):
+        assert _guess_provider("claude-sonnet-4-20250514") == "anthropic"
+
+    def test_gpt_is_openai(self):
+        assert _guess_provider("gpt-4o") == "openai"
+
+    def test_o_series_is_openai(self):
+        assert _guess_provider("o1-preview") == "openai"
+        assert _guess_provider("o3-mini") == "openai"
+
+    def test_llama_is_ollama(self):
+        assert _guess_provider("llama3.1") == "ollama"
+
+    def test_unknown_defaults_to_openai(self):
+        assert _guess_provider("some-unknown-model") == "openai"
+
+
+class TestLLMResponseFields:
+    def test_all_fields_populated(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        mock_resp = _mock_response({
+            "choices": [{"message": {"content": "test output"}}],
+            "usage": {"prompt_tokens": 80, "completion_tokens": 40},
+        })
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp):
+            result = llm_call("system", "user", model="openai/gpt-4o")
+
+        assert isinstance(result, LLMResponse)
+        assert result.text == "test output"
+        assert result.model == "gpt-4o"
+        assert result.provider == "openai"
+        assert result.input_tokens == 80
+        assert result.output_tokens == 40
+
+    def test_token_counts_from_anthropic(self, monkeypatch):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test")
+        mock_resp = _mock_response({
+            "content": [{"text": "hello"}],
+            "usage": {"input_tokens": 150, "output_tokens": 75},
+        })
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp):
+            result = llm_call("system", "user", model="anthropic/claude-sonnet-4-20250514")
+
+        assert result.input_tokens == 150
+        assert result.output_tokens == 75
+
+    def test_missing_usage_returns_none(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        mock_resp = _mock_response({"choices": [{"message": {"content": "no usage"}}]})
+
+        with patch("nthlayer_common.llm.httpx.post", return_value=mock_resp):
+            result = llm_call("system", "user", model="openai/gpt-4o")
+
+        assert result.input_tokens is None
+        assert result.output_tokens is None