hindsight-api 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

hindsight_api/api/mcp.py

@@ -4,27 +4,33 @@ import json
 import logging
 import os
 from contextvars import ContextVar
-from typing import Optional
 
 from fastmcp import FastMCP
+
 from hindsight_api import MemoryEngine
 from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
 
 # Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
 _log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
-_log_level_map = {"critical": logging.CRITICAL, "error": logging.ERROR, "warning": logging.WARNING,
-                  "info": logging.INFO, "debug": logging.DEBUG, "trace": logging.DEBUG}
+_log_level_map = {
+    "critical": logging.CRITICAL,
+    "error": logging.ERROR,
+    "warning": logging.WARNING,
+    "info": logging.INFO,
+    "debug": logging.DEBUG,
+    "trace": logging.DEBUG,
+}
 logging.basicConfig(
     level=_log_level_map.get(_log_level_str, logging.INFO),
-    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
 )
 logger = logging.getLogger(__name__)
 
 # Context variable to hold the current bank_id from the URL path
-_current_bank_id: ContextVar[Optional[str]] = ContextVar("current_bank_id", default=None)
+_current_bank_id: ContextVar[str | None] = ContextVar("current_bank_id", default=None)
 
 
-def get_current_bank_id() -> Optional[str]:
+def get_current_bank_id() -> str | None:
     """Get the current bank_id from context (set from URL path)."""
     return _current_bank_id.get()
 
@@ -61,10 +67,7 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
         """
         try:
             bank_id = get_current_bank_id()
-            await memory.put_batch_async(
-                bank_id=bank_id,
-                contents=[{"content": content, "context": context}]
-            )
+            await memory.retain_batch_async(bank_id=bank_id, contents=[{"content": content, "context": context}])
             return "Memory stored successfully"
         except Exception as e:
             logger.error(f"Error storing memory: {e}", exc_info=True)
@@ -88,11 +91,9 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
         try:
             bank_id = get_current_bank_id()
             from hindsight_api.engine.memory_engine import Budget
+
             search_result = await memory.recall_async(
-                bank_id=bank_id,
-                query=query,
-                fact_type=list(VALID_RECALL_FACT_TYPES),
-                budget=Budget.LOW
+                bank_id=bank_id, query=query, fact_type=list(VALID_RECALL_FACT_TYPES), budget=Budget.LOW
             )
 
             results = [
@@ -133,7 +134,7 @@ class MCPMiddleware:
         # Strip any mount prefix (e.g., /mcp) that FastAPI might not have stripped
         root_path = scope.get("root_path", "")
         if root_path and path.startswith(root_path):
-            path = path[len(root_path):] or "/"
+            path = path[len(root_path) :] or "/"
 
         # Also handle case where mount path wasn't stripped (e.g., /mcp/...)
         if path.startswith("/mcp/"):
@@ -169,10 +170,7 @@ class MCPMiddleware:
                     body = message.get("body", b"")
                     if body and b"/messages" in body:
                         # Rewrite /messages to /{bank_id}/messages in SSE endpoint event
-                        body = body.replace(
-                            b"data: /messages",
-                            f"data: /{bank_id}/messages".encode()
-                        )
+                        body = body.replace(b"data: /messages", f"data: /{bank_id}/messages".encode())
                         message = {**message, "body": body}
                 await send(message)
 
@@ -183,15 +181,19 @@ class MCPMiddleware:
     async def _send_error(self, send, status: int, message: str):
         """Send an error response."""
         body = json.dumps({"error": message}).encode()
-        await send({
-            "type": "http.response.start",
-            "status": status,
-            "headers": [(b"content-type", b"application/json")],
-        })
-        await send({
-            "type": "http.response.body",
-            "body": body,
-        })
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [(b"content-type", b"application/json")],
+            }
+        )
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body,
+            }
+        )
 
 
 def create_mcp_app(memory: MemoryEngine):

hindsight_api/banner.py

@@ -6,7 +6,7 @@ Shows the logo and tagline with gradient colors.
 
 # Gradient colors: #0074d9 -> #009296
 GRADIENT_START = (0, 116, 217)  # #0074d9
-GRADIENT_END = (0, 146, 150)    # #009296
+GRADIENT_END = (0, 146, 150)  # #009296
 
 # Pre-generated logo (generated by test-logo.py)
 LOGO = """\
@@ -31,8 +31,8 @@ def gradient_text(text: str, start: tuple = GRADIENT_START, end: tuple = GRADIEN
     result = []
     length = len(text)
     for i, char in enumerate(text):
-        if char == ' ':
-            result.append(' ')
+        if char == " ":
+            result.append(" ")
         else:
             t = i / max(length - 1, 1)
             r, g, b = _interpolate_color(start, end, t)
@@ -74,9 +74,16 @@ def dim(text: str) -> str:
     return f"\033[38;2;128;128;128m{text}\033[0m"
 
 
-def print_startup_info(host: str, port: int, database_url: str, llm_provider: str,
-                       llm_model: str, embeddings_provider: str, reranker_provider: str,
-                       mcp_enabled: bool = False):
+def print_startup_info(
+    host: str,
+    port: int,
+    database_url: str,
+    llm_provider: str,
+    llm_model: str,
+    embeddings_provider: str,
+    reranker_provider: str,
+    mcp_enabled: bool = False,
+):
     """Print styled startup information."""
     print(color_start("Starting Hindsight API..."))
     print(f"  {dim('URL:')} {color(f'http://{host}:{port}', 0.2)}")

hindsight_api/config.py

@@ -3,10 +3,10 @@ Centralized configuration for Hindsight API.
 
 All environment variables and their defaults are defined here.
 """
+
+import logging
 import os
 from dataclasses import dataclass
-from typing import Optional
-import logging
 
 logger = logging.getLogger(__name__)
 
@@ -30,6 +30,7 @@ ENV_PORT = "HINDSIGHT_API_PORT"
 ENV_LOG_LEVEL = "HINDSIGHT_API_LOG_LEVEL"
 ENV_MCP_ENABLED = "HINDSIGHT_API_MCP_ENABLED"
 ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
+ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
@@ -47,6 +48,7 @@ DEFAULT_PORT = 8888
 DEFAULT_LOG_LEVEL = "info"
 DEFAULT_MCP_ENABLED = True
 DEFAULT_GRAPH_RETRIEVER = "bfs"  # Options: "bfs", "mpfp"
+DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 
 # Required embedding dimension for database schema
 EMBEDDING_DIMENSION = 384
@@ -61,19 +63,19 @@ class HindsightConfig:
 
     # LLM
     llm_provider: str
-    llm_api_key: Optional[str]
+    llm_api_key: str | None
     llm_model: str
-    llm_base_url: Optional[str]
+    llm_base_url: str | None
 
     # Embeddings
     embeddings_provider: str
     embeddings_local_model: str
-    embeddings_tei_url: Optional[str]
+    embeddings_tei_url: str | None
 
     # Reranker
     reranker_provider: str
     reranker_local_model: str
-    reranker_tei_url: Optional[str]
+    reranker_tei_url: str | None
 
     # Server
     host: str
@@ -90,29 +92,24 @@ class HindsightConfig:
         return cls(
             # Database
             database_url=os.getenv(ENV_DATABASE_URL, DEFAULT_DATABASE_URL),
-
             # LLM
             llm_provider=os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER),
             llm_api_key=os.getenv(ENV_LLM_API_KEY),
             llm_model=os.getenv(ENV_LLM_MODEL, DEFAULT_LLM_MODEL),
             llm_base_url=os.getenv(ENV_LLM_BASE_URL) or None,
-
             # Embeddings
             embeddings_provider=os.getenv(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER),
             embeddings_local_model=os.getenv(ENV_EMBEDDINGS_LOCAL_MODEL, DEFAULT_EMBEDDINGS_LOCAL_MODEL),
             embeddings_tei_url=os.getenv(ENV_EMBEDDINGS_TEI_URL),
-
             # Reranker
             reranker_provider=os.getenv(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER),
             reranker_local_model=os.getenv(ENV_RERANKER_LOCAL_MODEL, DEFAULT_RERANKER_LOCAL_MODEL),
             reranker_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
-
             # Server
             host=os.getenv(ENV_HOST, DEFAULT_HOST),
             port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
             log_level=os.getenv(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL),
             mcp_enabled=os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() == "true",
-
             # Recall
             graph_retriever=os.getenv(ENV_GRAPH_RETRIEVER, DEFAULT_GRAPH_RETRIEVER),
         )
@@ -145,8 +142,7 @@ class HindsightConfig:
     def configure_logging(self) -> None:
         """Configure Python logging based on the log level."""
         logging.basicConfig(
-            level=self.get_python_log_level(),
-            format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+            level=self.get_python_log_level(), format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
         )
 
     def log_config(self) -> None:

hindsight_api/engine/__init__.py

@@ -7,24 +7,24 @@ This package contains all the implementation details of the memory engine:
 - Supporting modules: embeddings, cross_encoder, entity_resolver, etc.
 """
 
-from .memory_engine import MemoryEngine
+from .cross_encoder import CrossEncoderModel, LocalSTCrossEncoder, RemoteTEICrossEncoder
 from .db_utils import acquire_with_retry
 from .embeddings import Embeddings, LocalSTEmbeddings, RemoteTEIEmbeddings
-from .cross_encoder import CrossEncoderModel, LocalSTCrossEncoder, RemoteTEICrossEncoder
+from .llm_wrapper import LLMConfig
+from .memory_engine import MemoryEngine
+from .response_models import MemoryFact, RecallResult, ReflectResult
 from .search.trace import (
-    SearchTrace,
-    QueryInfo,
     EntryPoint,
-    NodeVisit,
-    WeightComponents,
     LinkInfo,
+    NodeVisit,
     PruningDecision,
-    SearchSummary,
+    QueryInfo,
     SearchPhaseMetrics,
+    SearchSummary,
+    SearchTrace,
+    WeightComponents,
 )
 from .search.tracer import SearchTracer
-from .llm_wrapper import LLMConfig
-from .response_models import RecallResult, ReflectResult, MemoryFact
 
 __all__ = [
     "MemoryEngine",

hindsight_api/engine/cross_encoder.py

@@ -5,19 +5,19 @@ Provides an interface for reranking with different backends.
 
 Configuration via environment variables - see hindsight_api.config for all env var names.
 """
-from abc import ABC, abstractmethod
-from typing import List, Tuple, Optional
+
 import logging
 import os
+from abc import ABC, abstractmethod
 
 import httpx
 
 from ..config import (
-    ENV_RERANKER_PROVIDER,
+    DEFAULT_RERANKER_LOCAL_MODEL,
+    DEFAULT_RERANKER_PROVIDER,
     ENV_RERANKER_LOCAL_MODEL,
+    ENV_RERANKER_PROVIDER,
     ENV_RERANKER_TEI_URL,
-    DEFAULT_RERANKER_PROVIDER,
-    DEFAULT_RERANKER_LOCAL_MODEL,
 )
 
 logger = logging.getLogger(__name__)
@@ -47,7 +47,7 @@ class CrossEncoderModel(ABC):
         pass
 
     @abstractmethod
-    def predict(self, pairs: List[Tuple[str, str]]) -> List[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
         """
         Score query-document pairs for relevance.
 
@@ -72,7 +72,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
     - Trained for passage re-ranking
     """
 
-    def __init__(self, model_name: Optional[str] = None):
+    def __init__(self, model_name: str | None = None):
         """
         Initialize local SentenceTransformers cross-encoder.
 
@@ -104,7 +104,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
         self._model = CrossEncoder(self.model_name)
         logger.info("Reranker: local provider initialized")
 
-    def predict(self, pairs: List[Tuple[str, str]]) -> List[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
         """
         Score query-document pairs for relevance.
 
@@ -117,7 +117,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
         if self._model is None:
             raise RuntimeError("Reranker not initialized. Call initialize() first.")
         scores = self._model.predict(pairs, show_progress_bar=False)
-        return scores.tolist() if hasattr(scores, 'tolist') else list(scores)
+        return scores.tolist() if hasattr(scores, "tolist") else list(scores)
 
 
 class RemoteTEICrossEncoder(CrossEncoderModel):
@@ -153,8 +153,8 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
         self.batch_size = batch_size
         self.max_retries = max_retries
         self.retry_delay = retry_delay
-        self._client: Optional[httpx.Client] = None
-        self._model_id: Optional[str] = None
+        self._client: httpx.Client | None = None
+        self._model_id: str | None = None
 
     @property
     def provider_name(self) -> str:
@@ -163,6 +163,7 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
     def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
         """Make an HTTP request with automatic retries on transient errors."""
         import time
+
         last_error = None
         delay = self.retry_delay
 
@@ -177,14 +178,18 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
             except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as e:
                 last_error = e
                 if attempt < self.max_retries:
-                    logger.warning(f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s...")
+                    logger.warning(
+                        f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
                     time.sleep(delay)
                     delay *= 2  # Exponential backoff
             except httpx.HTTPStatusError as e:
                 # Retry on 5xx server errors
                 if e.response.status_code >= 500 and attempt < self.max_retries:
                     last_error = e
-                    logger.warning(f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s...")
+                    logger.warning(
+                        f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
                     time.sleep(delay)
                     delay *= 2
                 else:
@@ -209,7 +214,7 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
         except httpx.HTTPError as e:
             raise RuntimeError(f"Failed to connect to TEI server at {self.base_url}: {e}")
 
-    def predict(self, pairs: List[Tuple[str, str]]) -> List[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
         """
         Score query-document pairs using the remote TEI reranker.
 
@@ -229,7 +234,7 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
 
         # Process in batches
         for i in range(0, len(pairs), self.batch_size):
-            batch = pairs[i:i + self.batch_size]
+            batch = pairs[i : i + self.batch_size]
 
             # TEI rerank endpoint expects query and texts separately
             # All pairs in a batch should have the same query for optimal performance
@@ -287,15 +292,11 @@ def create_cross_encoder_from_env() -> CrossEncoderModel:
     if provider == "tei":
         url = os.environ.get(ENV_RERANKER_TEI_URL)
         if not url:
-            raise ValueError(
-                f"{ENV_RERANKER_TEI_URL} is required when {ENV_RERANKER_PROVIDER} is 'tei'"
-            )
+            raise ValueError(f"{ENV_RERANKER_TEI_URL} is required when {ENV_RERANKER_PROVIDER} is 'tei'")
         return RemoteTEICrossEncoder(base_url=url)
     elif provider == "local":
         model = os.environ.get(ENV_RERANKER_LOCAL_MODEL)
         model_name = model or DEFAULT_RERANKER_LOCAL_MODEL
         return LocalSTCrossEncoder(model_name=model_name)
     else:
-        raise ValueError(
-            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei'"
-        )
+        raise ValueError(f"Unknown reranker provider: {provider}. Supported: 'local', 'tei'")

hindsight_api/engine/db_utils.py

@@ -1,9 +1,11 @@
 """
 Database utility functions for connection management with retry logic.
 """
+
 import asyncio
 import logging
 from contextlib import asynccontextmanager
+
 import asyncpg
 
 logger = logging.getLogger(__name__)
@@ -54,16 +56,14 @@ async def retry_with_backoff(
         except retryable_exceptions as e:
             last_exception = e
             if attempt < max_retries:
-                delay = min(base_delay * (2 ** attempt), max_delay)
+                delay = min(base_delay * (2**attempt), max_delay)
                 logger.warning(
                     f"Database operation failed (attempt {attempt + 1}/{max_retries + 1}): {e}. "
                     f"Retrying in {delay:.1f}s..."
                 )
                 await asyncio.sleep(delay)
             else:
-                logger.error(
-                    f"Database operation failed after {max_retries + 1} attempts: {e}"
-                )
+                logger.error(f"Database operation failed after {max_retries + 1} attempts: {e}")
     raise last_exception
 
 
@@ -83,6 +83,7 @@ async def acquire_with_retry(pool: asyncpg.Pool, max_retries: int = DEFAULT_MAX_
     Yields:
         An asyncpg connection
     """
+
     async def acquire():
         return await pool.acquire()
 

hindsight_api/engine/embeddings.py

@@ -8,20 +8,20 @@ the database schema (pgvector column defined as vector(384)).
 
 Configuration via environment variables - see hindsight_api.config for all env var names.
 """
-from abc import ABC, abstractmethod
-from typing import List, Optional
+
 import logging
 import os
+from abc import ABC, abstractmethod
 
 import httpx
 
 from ..config import (
-    ENV_EMBEDDINGS_PROVIDER,
-    ENV_EMBEDDINGS_LOCAL_MODEL,
-    ENV_EMBEDDINGS_TEI_URL,
-    DEFAULT_EMBEDDINGS_PROVIDER,
     DEFAULT_EMBEDDINGS_LOCAL_MODEL,
+    DEFAULT_EMBEDDINGS_PROVIDER,
     EMBEDDING_DIMENSION,
+    ENV_EMBEDDINGS_LOCAL_MODEL,
+    ENV_EMBEDDINGS_PROVIDER,
+    ENV_EMBEDDINGS_TEI_URL,
 )
 
 logger = logging.getLogger(__name__)
@@ -52,7 +52,7 @@ class Embeddings(ABC):
         pass
 
     @abstractmethod
-    def encode(self, texts: List[str]) -> List[List[float]]:
+    def encode(self, texts: list[str]) -> list[list[float]]:
         """
         Generate 384-dimensional embeddings for a list of texts.
 
@@ -75,7 +75,7 @@ class LocalSTEmbeddings(Embeddings):
     embeddings matching the database schema.
     """
 
-    def __init__(self, model_name: Optional[str] = None):
+    def __init__(self, model_name: str | None = None):
         """
         Initialize local SentenceTransformers embeddings.
 
@@ -123,7 +123,7 @@ class LocalSTEmbeddings(Embeddings):
 
         logger.info(f"Embeddings: local provider initialized (dim: {model_dim})")
 
-    def encode(self, texts: List[str]) -> List[List[float]]:
+    def encode(self, texts: list[str]) -> list[list[float]]:
         """
         Generate 384-dimensional embeddings for a list of texts.
 
@@ -172,8 +172,8 @@ class RemoteTEIEmbeddings(Embeddings):
         self.batch_size = batch_size
         self.max_retries = max_retries
         self.retry_delay = retry_delay
-        self._client: Optional[httpx.Client] = None
-        self._model_id: Optional[str] = None
+        self._client: httpx.Client | None = None
+        self._model_id: str | None = None
 
     @property
     def provider_name(self) -> str:
@@ -182,6 +182,7 @@ class RemoteTEIEmbeddings(Embeddings):
     def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
         """Make an HTTP request with automatic retries on transient errors."""
         import time
+
         last_error = None
         delay = self.retry_delay
 
@@ -196,14 +197,18 @@ class RemoteTEIEmbeddings(Embeddings):
             except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as e:
                 last_error = e
                 if attempt < self.max_retries:
-                    logger.warning(f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s...")
+                    logger.warning(
+                        f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
                     time.sleep(delay)
                     delay *= 2  # Exponential backoff
             except httpx.HTTPStatusError as e:
                 # Retry on 5xx server errors
                 if e.response.status_code >= 500 and attempt < self.max_retries:
                     last_error = e
-                    logger.warning(f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s...")
+                    logger.warning(
+                        f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
                     time.sleep(delay)
                     delay *= 2
                 else:
@@ -228,7 +233,7 @@ class RemoteTEIEmbeddings(Embeddings):
         except httpx.HTTPError as e:
             raise RuntimeError(f"Failed to connect to TEI server at {self.base_url}: {e}")
 
-    def encode(self, texts: List[str]) -> List[List[float]]:
+    def encode(self, texts: list[str]) -> list[list[float]]:
         """
         Generate embeddings using the remote TEI server.
 
@@ -248,7 +253,7 @@ class RemoteTEIEmbeddings(Embeddings):
 
         # Process in batches
         for i in range(0, len(texts), self.batch_size):
-            batch = texts[i:i + self.batch_size]
+            batch = texts[i : i + self.batch_size]
 
             try:
                 response = self._request_with_retry(
@@ -278,15 +283,11 @@ def create_embeddings_from_env() -> Embeddings:
     if provider == "tei":
         url = os.environ.get(ENV_EMBEDDINGS_TEI_URL)
         if not url:
-            raise ValueError(
-                f"{ENV_EMBEDDINGS_TEI_URL} is required when {ENV_EMBEDDINGS_PROVIDER} is 'tei'"
-            )
+            raise ValueError(f"{ENV_EMBEDDINGS_TEI_URL} is required when {ENV_EMBEDDINGS_PROVIDER} is 'tei'")
         return RemoteTEIEmbeddings(base_url=url)
     elif provider == "local":
         model = os.environ.get(ENV_EMBEDDINGS_LOCAL_MODEL)
         model_name = model or DEFAULT_EMBEDDINGS_LOCAL_MODEL
         return LocalSTEmbeddings(model_name=model_name)
     else:
-        raise ValueError(
-            f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei'"
-        )
+        raise ValueError(f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei'")