Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
"""Configuration management for Hyper-Extract CLI."""
import json
import logging
import os
import subprocess
import tomllib
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import tomli_w
from hyperextract.utils.client import PROVIDER_API_KEY_ENV, PROVIDER_PRESETS
logger = logging.getLogger(__name__)
# Owner read/write only. Group/other bits that make a file too open.
_CONFIG_FILE_MODE = 0o600
_GROUP_OTHER_BITS = 0o077
DEFAULT_CONFIG_DIR = Path.home() / ".he"
DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "config.toml"
def _env_api_key(provider: str) -> str:
"""Return the first non-empty API key from the provider's env vars.
Falls back to OPENAI_API_KEY for OpenAI-compatible providers.
"""
for var in PROVIDER_API_KEY_ENV.get(provider, ("OPENAI_API_KEY",)):
value = os.environ.get(var, "")
if value:
return value
return ""
def _restrict_config_permissions(path: Path) -> None:
"""Set *path* to owner read/write only. POSIX 0600; Windows owner DACL."""
if os.name == "nt":
_restrict_windows_acl(path)
return
try:
os.chmod(path, _CONFIG_FILE_MODE)
except OSError:
pass
def _icacls(*args: str) -> subprocess.CompletedProcess:
return subprocess.run(
["icacls", *args],
capture_output=True,
check=False,
)
def _icacls_text(result: subprocess.CompletedProcess) -> str:
"""Decode icacls output; Windows uses the ANSI code page, not UTF-8."""
def _decode(data: bytes | None) -> str:
if not data:
return ""
if os.name == "nt":
return data.decode("mbcs", errors="replace")
return data.decode("utf-8", errors="replace")
return f"{_decode(result.stdout)}\n{_decode(result.stderr)}"
def _windows_account() -> str:
user = os.environ.get("USERNAME", "").strip()
domain = os.environ.get("USERDOMAIN", "").strip()
if user and domain and domain.upper() != user.upper():
return f"{domain}\\{user}"
return user
def _restrict_windows_acl(path: Path) -> None:
"""Grant the current user FullControl; drop Everyone/Users inherited read."""
account = _windows_account()
if not account:
return
target = str(path)
# Grant first so stripping inheritance cannot lock the file out.
_icacls(target, "/grant:r", f"{account}:(F)")
_icacls(target, "/inheritance:r")
for principal in (
"Everyone",
"*S-1-1-0",
"Users",
"BUILTIN\\Users",
"Authenticated Users",
):
_icacls(target, "/remove:g", principal)
def _windows_acl_everyone_readable(path: Path) -> bool:
"""True when icacls reports Everyone with a read-class right."""
text = _icacls_text(_icacls(str(path)))
for line in text.splitlines():
stripped = line.strip()
if "Everyone:" not in stripped and "S-1-1-0" not in stripped:
continue
if ":(" in stripped:
return True
return False
def _warn_if_insecure_permissions(path: Path) -> None:
"""Warn when group, others, or Everyone can read the config file."""
if os.name == "nt":
if _windows_acl_everyone_readable(path):
logger.warning(
"Config file %s is readable by Everyone. "
"The next `he config` save will restrict the ACL to the "
"current user.",
path,
)
return
try:
mode = path.stat().st_mode
except OSError:
return
if mode & _GROUP_OTHER_BITS:
logger.warning(
"Config file %s is readable by group or others (mode %04o). "
"The next `he config` save will tighten it to 0600, "
"or run: chmod 600 %s",
path,
mode & 0o777,
path,
)
@dataclass
class LLMConfig:
provider: str = ""
model: str = "gpt-4o-mini"
api_key: str = ""
base_url: str = ""
def to_dict(self) -> dict[str, Any]:
return {
"provider": self.provider,
"model": self.model,
"api_key": self.api_key,
"base_url": self.base_url,
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> "LLMConfig":
return cls(
provider=data.get("provider", ""),
model=data.get("model", "gpt-4o-mini"),
api_key=data.get("api_key", ""),
base_url=data.get("base_url", ""),
)
@dataclass
class EmbedderConfig:
provider: str = ""
model: str = "text-embedding-3-small"
api_key: str = ""
base_url: str = ""
def to_dict(self) -> dict[str, Any]:
return {
"provider": self.provider,
"model": self.model,
"api_key": self.api_key,
"base_url": self.base_url,
}
@classmethod
def from_dict(cls, data: dict[str, Any]) -> "EmbedderConfig":
return cls(
provider=data.get("provider", ""),
model=data.get("model", "text-embedding-3-small"),
api_key=data.get("api_key", ""),
base_url=data.get("base_url", ""),
)
class ConfigManager:
"""Manages Hyper-Extract CLI configuration."""
def __init__(self, config_path: Path | None = None):
self.config_path = config_path or DEFAULT_CONFIG_FILE
self.llm = LLMConfig()
self.embedder = EmbedderConfig()
self._load()
def _load(self) -> None:
"""Load configuration from file."""
if not self.config_path.exists():
return
_warn_if_insecure_permissions(self.config_path)
with open(self.config_path, "rb") as f:
data = tomllib.load(f)
if "llm" in data:
self.llm = LLMConfig.from_dict(data["llm"])
if "embedder" in data:
self.embedder = EmbedderConfig.from_dict(data["embedder"])
def _save(self) -> None:
"""Save configuration to file."""
# Create the parent of the actual target path, not the default dir —
# a custom config_path may live elsewhere and would otherwise 404.
self.config_path.parent.mkdir(parents=True, exist_ok=True)
data = {
"llm": self.llm.to_dict(),
"embedder": self.embedder.to_dict(),
}
with open(self.config_path, "wb") as f:
tomli_w.dump(data, f)
_restrict_config_permissions(self.config_path)
def _resolve_base_url(self, provider: str, explicit_base_url: str) -> str:
"""Resolve base_url from provider preset. Explicit value takes precedence."""
if explicit_base_url:
return explicit_base_url
if provider in PROVIDER_PRESETS:
preset_url = PROVIDER_PRESETS[provider].get("base_url")
if preset_url is None:
raise ValueError(
f"Provider '{provider}' requires explicit base_url. "
f"Please set it via config or environment variable."
)
return preset_url
return ""
def get_llm_config(self) -> LLMConfig:
"""Get LLM config with environment variable fallback."""
config = LLMConfig(
provider=self.llm.provider,
model=self.llm.model,
api_key=self.llm.api_key or _env_api_key(self.llm.provider),
base_url=self._resolve_base_url(
self.llm.provider,
self.llm.base_url or os.environ.get("OPENAI_BASE_URL", ""),
),
)
return config
def get_embedder_config(self) -> EmbedderConfig:
"""Get Embedder config with environment variable fallback."""
config = EmbedderConfig(
provider=self.embedder.provider,
model=self.embedder.model,
api_key=self.embedder.api_key or _env_api_key(self.embedder.provider),
base_url=self._resolve_base_url(
self.embedder.provider,
self.embedder.base_url or os.environ.get("OPENAI_BASE_URL", ""),
),
)
return config
def set_llm(
self,
provider: str | None = None,
model: str | None = None,
api_key: str | None = None,
base_url: str | None = None,
) -> None:
"""Set LLM configuration."""
if provider is not None:
self.llm.provider = provider
if model:
self.llm.model = model
if api_key is not None:
self.llm.api_key = api_key
if base_url is not None:
self.llm.base_url = base_url
self._save()
def set_embedder(
self,
provider: str | None = None,
model: str | None = None,
api_key: str | None = None,
base_url: str | None = None,
) -> None:
"""Set Embedder configuration."""
if provider is not None:
self.embedder.provider = provider
if model:
self.embedder.model = model
if api_key is not None:
self.embedder.api_key = api_key
if base_url is not None:
self.embedder.base_url = base_url
self._save()
def unset_llm(self) -> None:
"""Unset LLM configuration."""
self.llm = LLMConfig()
self._save()
def unset_embedder(self) -> None:
"""Unset Embedder configuration."""
self.embedder = EmbedderConfig()
self._save()
def show(self) -> dict[str, Any]:
"""Show current configuration."""
return {
"llm": self.get_llm_config().to_dict(),
"embedder": self.get_embedder_config().to_dict(),
}
def validate(self) -> tuple[bool, str]:
"""Validate configuration."""
llm_config = self.get_llm_config()
embedder_config = self.get_embedder_config()
# vLLM mode: api_key can be empty or dummy, but base_url is required
if llm_config.provider == "vllm":
if not llm_config.base_url:
return False, "vLLM provider requires base_url."
elif not llm_config.api_key:
return (
False,
"LLM API key is not configured. Run 'he config llm --api-key YOUR_KEY'",
)
if embedder_config.provider == "vllm":
if not embedder_config.base_url:
return False, "vLLM embedder requires base_url."
elif not embedder_config.api_key:
return (
False,
"Embedder API key is not configured. Run 'he config embedder --api-key YOUR_KEY'",
)
return True, "Configuration is valid"
def load_ka_metadata(ka_path: Path) -> dict[str, Any] | None:
"""Load knowledge abstract metadata from directory."""
metadata_path = ka_path / "metadata.json"
if not metadata_path.exists():
return None
with open(metadata_path, "r", encoding="utf-8") as f:
return json.load(f)