deriva-cli 0.8.3__tar.gz → 0.8.4__tar.gz

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deriva-cli
-Version: 0.8.3
+Version: 0.8.4
 Summary: Deriva is a research project aimed at enabling digital architects by automating the derivation of enterprise architecture models. Deriva uses dual knowledge graphs, heuristics and LLM's.
 Keywords: archimate,enterprise-architecture,code-analysis,llm,grafeo,fastapi
 Author: S. T. Grond
@@ -38,8 +38,8 @@ Requires-Dist: spacy==3.8.16
 Requires-Dist: ctranslate2==4.8.3
 Requires-Dist: sentencepiece==0.2.2
 Requires-Dist: solvor>=0.6.3
-Requires-Dist: pydantic-ai-slim[openai,anthropic]>=2.55
-Requires-Dist: httpx2>=2.13
+Requires-Dist: pydantic-ai-slim[openai,anthropic]>=2.57
+Requires-Dist: httpx2>=2.14
 Requires-Dist: lmdb>=1.6
 Requires-Dist: typer>=0.27
 Requires-Dist: tree-sitter-typescript==0.23.2

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/grafeo/__init__.py

@@ -21,9 +21,13 @@ from .manager import (
     DEFAULT_DATABASE,
     GrafeoConnection,
     close_database,
+    database_bytes,
+    database_exists,
     database_file,
+    delete_database,
     engine_info,
     get_database,
+    list_databases,
     use_database,
 )
 
@@ -31,8 +35,12 @@ __all__ = [
     "DEFAULT_DATABASE",
     "GrafeoConnection",
     "close_database",
+    "database_bytes",
+    "database_exists",
     "database_file",
+    "delete_database",
     "engine_info",
     "get_database",
+    "list_databases",
     "use_database",
 ]

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/grafeo/manager.py

@@ -27,8 +27,10 @@ Usage:
 from __future__ import annotations
 
 import logging
+import shutil
 import time
 import weakref
+from pathlib import Path
 from typing import Any
 
 from deriva.common.paths import resolve
@@ -77,6 +79,55 @@ def database_file(key: str) -> str | None:
     return str(folder / f"{key}.grafeo")
 
 
+def _stored_paths(key: str) -> tuple[Path, Path] | None:
+    """The key's database file and its write-ahead log folder, never created (None in memory or for an invalid key)."""
+    directory = GrafeoSettings().db_dir
+    if not directory or not key or key in (".", "..") or any(sep in key for sep in ("/", "\\")):
+        return None
+    folder = resolve(directory)
+    return folder / f"{key}.grafeo", folder / f"{key}.grafeo.wal"
+
+
+def database_exists(key: str) -> bool:
+    """Whether the key's database file exists; never creates it or its folder (False in memory or for an invalid key)."""
+    paths = _stored_paths(key)
+    return paths is not None and paths[0].exists()
+
+
+def list_databases() -> list[str]:
+    """The keys with a database file in GRAFEO_DB_DIR, sorted (none in memory)."""
+    directory = GrafeoSettings().db_dir
+    folder = resolve(directory) if directory else None
+    if folder is None or not folder.is_dir():
+        return []
+    return sorted(path.name.removesuffix(".grafeo") for path in folder.glob("*.grafeo") if path.is_file())
+
+
+def database_bytes(key: str) -> int:
+    """Bytes the key's database takes on disk: its file and its write-ahead log (0 when it has none)."""
+    paths = _stored_paths(key)
+    if paths is None:
+        return 0
+    database, log = paths
+    size = database.stat().st_size if database.is_file() else 0
+    return size + (sum(f.stat().st_size for f in log.rglob("*") if f.is_file()) if log.is_dir() else 0)
+
+
+def delete_database(key: str) -> bool:
+    """Delete the key's database file and log; False when it had none. The active database is never deleted (switch
+    away first): a query after the delete would create a new, empty file."""
+    if key == _db_key:
+        raise ValueError(f"The database {key!r} is open; switch to another one before deleting it")
+    paths = _stored_paths(key)
+    if paths is None or not (paths[0].exists() or paths[1].exists()):
+        return False
+    database, log = paths
+    database.unlink(missing_ok=True)
+    if log.is_dir():
+        shutil.rmtree(log)
+    return True
+
+
 def get_database() -> Any:
     """Get or open the active GrafeoDB instance (see ``use_database``).
 

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/graph/manager.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 
 import logging
 import re
-from collections.abc import Iterator
+from collections.abc import Generator
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import Any
@@ -280,7 +280,7 @@ class GraphManager:
             raise
 
     @contextmanager
-    def step_tags(self, step: str, version: int | None = None) -> Iterator[None]:
+    def step_tags(self, step: str, version: int | None = None) -> Generator[None]:
         """Nodes and edges written inside the block carry the extraction step (``extractStep``) and its version."""
         previous = self._step_tags
         self._step_tags = {"extractStep": step, **({"extractVersion": version} if version is not None else {})}
@@ -290,7 +290,7 @@ class GraphManager:
             self._step_tags = previous
 
     @contextmanager
-    def recording(self) -> Iterator[GraphWrites]:
+    def recording(self) -> Generator[GraphWrites]:
         """The nodes and edges written inside the block (for the run log); failed writes are left out."""
         recorder = GraphWrites()
         self._recorders.append(recorder)

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/graph/metamodel.py

@@ -13,6 +13,10 @@ from typing import Any
 from . import models
 
 __all__ = [
+    "GROUP_ORDER",
+    "NODE_GROUPS",
+    "node_description",
+    "node_group",
     "get_all_node_classes",
     "get_node_properties",
     "get_relationship_types",
@@ -36,7 +40,45 @@ def get_all_node_classes() -> dict[str, type]:
     return node_classes
 
 
-def get_node_properties(node_class: type) -> list[str]:
+# The intermediate ontology's groups (as ArchiMate has its layers): where a node type's evidence comes from
+GROUP_ORDER = ("structure", "code", "business", "deployment")
+NODE_GROUPS = {
+    "Repository": "structure",
+    "Directory": "structure",
+    "File": "structure",
+    "Module": "structure",
+    "BuildModule": "structure",
+    "TypeDefinition": "code",
+    "Method": "code",
+    "Test": "code",
+    "ExternalDependency": "code",
+    "Service": "code",
+    "BusinessConcept": "business",
+    "DataEntity": "business",
+    "DataDomain": "business",
+    "Lifecycle": "business",
+    "LifecycleEvent": "business",
+    "Role": "business",
+    "DeployableUnit": "deployment",
+    "Deployment": "deployment",
+    "Environment": "deployment",
+    "Software": "deployment",
+    "Technology": "deployment",
+}
+
+
+def node_group(node_type: str) -> str:
+    """The group of a node type (``other`` for a label the metamodel does not name)."""
+    return NODE_GROUPS.get(node_type, "other")
+
+
+def node_description(node_class: type) -> str:
+    """The first line of a node class's docstring."""
+    lines = (node_class.__doc__ or "").strip().splitlines()
+    return lines[0].strip() if lines else ""
+
+
+def get_node_properties(node_class: type[Any]) -> list[str]:
     """Get all property names for a node class.
 
     Args:

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/llm/manager.py

@@ -43,8 +43,9 @@ from typing import Any, TypeVar, cast, overload
 
 import httpx2
 from pydantic import BaseModel
-from pydantic_ai import Agent
-from pydantic_ai.exceptions import ModelHTTPError
+from pydantic_ai import Agent, capture_run_messages
+from pydantic_ai.exceptions import IncompleteToolCall, ModelHTTPError
+from pydantic_ai.messages import ModelResponse
 from pydantic_ai.settings import ModelSettings
 
 from deriva.common import settings
@@ -53,7 +54,7 @@ from deriva.common.paths import resolve
 from deriva.common.settings import LlmSettings
 
 from .cache import CacheManager
-from .model_registry import VALID_PROVIDERS, get_pydantic_ai_model, parse_sampling, reasoning_settings
+from .model_registry import VALID_PROVIDERS, default_sampling, get_pydantic_ai_model, parse_sampling, reasoning_settings
 from .models import (
     BenchmarkModelConfig,
     CachedResponse,
@@ -214,9 +215,10 @@ def load_benchmark_models() -> dict[str, BenchmarkModelConfig]:
                 api_url=fields["url"],
                 api_key=fields["key"],
                 api_key_env=fields["key_env"],
-                sampling=parse_sampling(fields.get("sampling")),
+                sampling=parse_sampling(fields.get("sampling"), provider.lower(), model),
                 reasoning=(fields.get("reasoning") or "").strip().lower() or None,
                 temperature=float(own) if (own := (fields.get("temperature") or "").strip()) else None,
+                context=int(size) if (size := (fields.get("context") or "").strip()) else None,
             )
         except ValueError:
             continue
@@ -224,6 +226,22 @@ def load_benchmark_models() -> dict[str, BenchmarkModelConfig]:
     return configs
 
 
+def _key_variable(config: BenchmarkModelConfig) -> str:
+    """The variable a model config's key is read from: its KEY_ENV reference, or its own LLM_{NAME}_KEY."""
+    return config.api_key_env or f"LLM_{config.name.upper().replace('-', '_')}_KEY"
+
+
+def _has_cut_response(history: Any) -> bool:
+    """Whether a model response in a run's messages stopped at the output limit (finish reason ``length``)."""
+    return any(isinstance(m, ModelResponse) and m.finish_reason == "length" for m in history or [])
+
+
+def _was_cut(result: Any) -> bool:
+    """Whether a model response in the run's result stopped at the output limit."""
+    messages = getattr(result, "all_messages", None)
+    return _has_cut_response(messages() if callable(messages) else [])
+
+
 def _serialize_output(output: object) -> str:
     """Serialize a pydantic model or arbitrary output to a JSON string."""
     dump = getattr(output, "model_dump_json", None)
@@ -314,6 +332,7 @@ class LLMManager:
         self.max_tokens = self.config.get("max_tokens")
         self.sampling = self.config.get("sampling", True)
         self.reasoning = self.config.get("reasoning")
+        self.context = self.config.get("context")
 
     @classmethod
     def from_config(
@@ -349,6 +368,8 @@ class LLMManager:
             "provider": config.provider,
             "api_url": config.get_api_url(),
             "api_key": config.get_api_key(),
+            "api_key_variable": _key_variable(config),
+            "label": config.name,
             "model": config.model,
             "cache_dir": cache_dir,
             "max_retries": max_retries,
@@ -357,6 +378,7 @@ class LLMManager:
             "nocache": nocache,
             "sampling": config.sampling,
             "reasoning": config.reasoning,
+            "context": config.context,
         }
 
         instance._validate_config()
@@ -389,6 +411,7 @@ class LLMManager:
         instance.max_tokens = None
         instance.sampling = config.sampling
         instance.reasoning = config.reasoning
+        instance.context = config.context
 
         return instance
 
@@ -397,6 +420,22 @@ class LLMManager:
         """Get the provider name."""
         return self.config.get("provider", "unknown")
 
+    def _warn_on_a_full_context(self, result: Any) -> None:
+        """A call whose last request used the model's whole context (when the config names it) lost part of its prompt
+        or answer: a local server such as Ollama cuts a prompt longer than its window without an error."""
+        if not self.context:
+            return
+        usage = getattr(getattr(result, "response", None), "usage", None)
+        used = (getattr(usage, "input_tokens", 0) or 0) + (getattr(usage, "output_tokens", 0) or 0)
+        if used >= self.context:
+            logger.warning(
+                "An LLM call used %d tokens of %s's %d-token context: part of the prompt or the answer was cut. "
+                "Raise the server's context (Ollama: OLLAMA_CONTEXT_LENGTH) and the model's context setting",
+                used,
+                self.model,
+                self.context,
+            )
+
     def _redact(self, text: str) -> str:
         """Keep the configured API key out of exception text: h11 quotes header values in its errors."""
         key = self.config.get("api_key")
@@ -417,11 +456,13 @@ class LLMManager:
             provider = config.provider
             api_url = config.get_api_url()
             api_key = config.get_api_key()
+            key_variable, label = _key_variable(config), config.name
             model = config.model
-            sampling, reasoning = config.sampling, config.reasoning
+            sampling, reasoning, context = config.sampling, config.reasoning, config.context
         else:
             provider = llm.provider
-            sampling, reasoning = True, None
+            reasoning, context = None, None
+            key_variable, label = f"LLM_{(provider or '').upper()}_API_KEY", provider
 
             if provider == "azure":
                 api_url = llm.azure_api_url
@@ -449,6 +490,7 @@ class LLMManager:
                 model = llm.lmstudio_model
             else:
                 raise ConfigurationError(f"Unknown LLM provider: {provider}")
+            sampling = default_sampling(provider, model)
 
         max_tokens = llm.max_tokens
 
@@ -456,6 +498,8 @@ class LLMManager:
             "provider": provider,
             "api_url": api_url,
             "api_key": api_key,
+            "api_key_variable": key_variable,
+            "label": label,
             "model": model,
             "cache_dir": llm.cache_dir,
             "cache_ttl": llm.cache_ttl,
@@ -466,6 +510,7 @@ class LLMManager:
             "nocache": llm.nocache,
             "sampling": sampling,
             "reasoning": reasoning,
+            "context": context,
             "requests_per_minute": llm.rate_limit_rpm,
             "min_request_delay": llm.rate_limit_delay,
             # Retry configuration
@@ -494,6 +539,12 @@ class LLMManager:
             required_fields = ["provider", "api_key", "model"]
 
         missing = [f for f in required_fields if not self.config.get(f)]
+        # The variable to set and the .env this install reads, never a value
+        if "api_key" in missing and self.config.get("api_key_variable"):
+            raise ConfigurationError(
+                f"The model config {self.config.get('label') or provider} has no API key: set {self.config['api_key_variable']} "
+                f"in {settings.env_file()} or in the environment (General in the studio saves a key there)"
+            )
         if missing:
             raise ConfigurationError(f"Missing required config fields: {', '.join(missing)}")
 
@@ -555,7 +606,7 @@ class LLMManager:
         max_delay = self.config.get("retry_max_delay", 60.0)
         for attempt in range(self.max_retries + 1):
             try:
-                return agent.run_sync(prompt, model_settings=settings), attempt
+                return self._run_once(agent, prompt, settings), attempt
             except Exception as e:
                 if attempt == self.max_retries or not _is_retriable(e):
                     raise
@@ -579,6 +630,19 @@ class LLMManager:
                 time.sleep(delay)
         raise AssertionError("unreachable")
 
+    @staticmethod
+    def _run_once(agent: Agent[None, Any], prompt: str, settings: ModelSettings) -> Any:
+        """One agent run. pydantic-ai asks again after an answer cut at the output limit; when those answers fail
+        too it raises "Exceeded maximum output retries", which is the cut: raised as IncompleteToolCall."""
+        with capture_run_messages() as messages:
+            try:
+                return agent.run_sync(prompt, model_settings=settings)
+            except Exception as e:
+                if not isinstance(e, IncompleteToolCall) and _has_cut_response(messages):
+                    limit = settings.get("max_tokens") or "provider default"
+                    raise IncompleteToolCall(f"Model token limit ({limit}) reached: the answer was cut, and the answers after it failed ({e})") from e
+                raise
+
     def _agent(self, output_type: Any, system_prompt: str) -> Agent[None, Any]:
         """Reusable agent for this output type and system prompt, per thread (created lazily).
 
@@ -756,6 +820,16 @@ class LLMManager:
                     "total_tokens": run_usage.input_tokens + run_usage.output_tokens,
                 }
 
+            self._warn_on_a_full_context(result)
+
+            # A structured answer cut at the output limit is asked again by pydantic-ai, and a shorter answer that
+            # validates can leave part of the question out: a failure (never cached), which a caller can split
+            if output_type is not str and _was_cut(result):
+                call["error_type"] = "IncompleteToolCall"
+                message = f"Model token limit ({effective_max_tokens or 'provider default'}) reached: the answer was cut, and the shorter answer after it may leave part of it out"
+                logger.warning("LLM answer cut at the output limit (%s)", self.model)
+                return FailedResponse(prompt=prompt, model=self.model, error=message, error_type="IncompleteToolCall")
+
             # Handle response
             output: Any = result.output
 

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/llm/model_registry.py

@@ -29,10 +29,21 @@ PROVIDER_REASONING_LEVELS = {
 _SAMPLING_VALUES = {"true": True, "1": True, "yes": True, "on": True, "false": False, "0": False, "no": False, "off": False}
 
 
-def parse_sampling(value: str | None) -> bool:
-    """LLM_{NAME}_SAMPLING: off for models that take no temperature (unset means on)."""
+def default_sampling(provider: str, model: str) -> bool:
+    """Whether a model takes a temperature when its config does not say. pydantic-ai's model profile knows the Anthropic
+    models that refuse sampling settings (it drops them, with a warning on every call); any other model takes one."""
+    if provider == "anthropic":
+        from pydantic_ai.profiles.anthropic import anthropic_model_profile
+
+        profile = anthropic_model_profile(model) or {}
+        return not profile.get("anthropic_disallows_sampling_settings", False)
+    return True
+
+
+def parse_sampling(value: str | None, provider: str = "", model: str = "") -> bool:
+    """LLM_{NAME}_SAMPLING: off for models that take no temperature (unset: what the model's profile says)."""
     if value is None or not value.strip():
-        return True
+        return default_sampling(provider, model)
     if value.strip().lower() not in _SAMPLING_VALUES:
         raise ValueError(f"sampling must be true or false, got {value!r}")
     return _SAMPLING_VALUES[value.strip().lower()]
@@ -126,6 +137,12 @@ def get_pydantic_ai_model(config: dict[str, Any]) -> Model | str:
         from pydantic_ai.models.openai import OpenAIChatModel
         from pydantic_ai.providers.azure import AzureProvider
 
+        # Azure's v1 API (<resource>/openai/v1/) is OpenAI's and takes no api_version: the OpenAI client goes there
+        if api_url and "/openai/v1" in api_url:
+            from pydantic_ai.providers.openai import OpenAIProvider
+
+            base_url = api_url[: api_url.index("/openai/v1") + len("/openai/v1")]
+            return OpenAIChatModel(model, provider=OpenAIProvider(base_url=base_url, api_key=api_key))
         azure_endpoint = _normalize_azure_url(api_url) if api_url else None
         azure_provider = AzureProvider(
             azure_endpoint=azure_endpoint,

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/llm/models.py

@@ -69,6 +69,7 @@ class BenchmarkModelConfig:
         sampling: False for models that take no temperature (Claude Haiku 5.5); the call leaves it out
         reasoning: Reasoning level ("none" turns it off; see ``model_registry.reasoning_settings``)
         temperature: The model's own temperature (0 to 2), over LLM_TEMPERATURE; unused when sampling is off
+        context: The model's context size in tokens, when known (a local server's window); a call that fills it is warned
     """
 
     name: str
@@ -80,6 +81,7 @@ class BenchmarkModelConfig:
     sampling: bool = True
     reasoning: str | None = None
     temperature: float | None = None
+    context: int | None = None
 
     def __post_init__(self):
         """Validate provider and reasoning level."""
@@ -97,6 +99,8 @@ class BenchmarkModelConfig:
         reasoning_settings(self.provider, self.reasoning)
         if self.temperature is not None and not 0.0 <= self.temperature <= 2.0:
             raise ValueError(f"temperature must be between 0 and 2, got {self.temperature}")
+        if self.context is not None and self.context < 1:
+            raise ValueError(f"context must be a positive number of tokens, got {self.context}")
 
     def get_api_key(self) -> str | None:
         """Get API key from direct value or environment variable."""
@@ -143,7 +147,7 @@ class BaseResponse(BaseModel):
 class LiveResponse(BaseResponse):
     """Response from a live API call."""
 
-    response_type: Literal[ResponseType.LIVE] = ResponseType.LIVE
+    response_type: Literal[ResponseType.LIVE] = ResponseType.LIVE  # ty: ignore[invalid-mutable-override]: the discriminator of a pydantic union
     content: str
     usage: dict[str, Any] | None = None
     finish_reason: str | None = None
@@ -152,7 +156,7 @@ class LiveResponse(BaseResponse):
 class CachedResponse(BaseResponse):
     """Response retrieved from cache."""
 
-    response_type: Literal[ResponseType.CACHED] = ResponseType.CACHED
+    response_type: Literal[ResponseType.CACHED] = ResponseType.CACHED  # ty: ignore[invalid-mutable-override]: the discriminator of a pydantic union
     content: str
     cache_key: str
     cached_at: str
@@ -161,7 +165,7 @@ class CachedResponse(BaseResponse):
 class FailedResponse(BaseResponse):
     """Response when API call fails."""
 
-    response_type: Literal[ResponseType.FAILED] = ResponseType.FAILED
+    response_type: Literal[ResponseType.FAILED] = ResponseType.FAILED  # ty: ignore[invalid-mutable-override]: the discriminator of a pydantic union
     error: str
     error_type: str
 

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/llm/retry.py

@@ -9,7 +9,7 @@ wrapper exceptions.
 from __future__ import annotations
 
 import httpx2
-from pydantic_ai.exceptions import ModelHTTPError
+from pydantic_ai.exceptions import IncompleteToolCall, ModelHTTPError
 
 from deriva.common.exceptions import (
     CircuitOpenError,
@@ -72,6 +72,10 @@ def classify_exception(
     if isinstance(exception, CircuitOpenError):
         return ("permanent", None)
 
+    # An answer cut at the output limit is cut again for the same prompt; the caller can split it instead
+    if isinstance(exception, IncompleteToolCall):
+        return ("permanent", None)
+
     # An HTTP status error carries its own status code
     if isinstance(exception, ModelHTTPError):
         status_code = getattr(exception, "status_code", None)

{deriva_cli-0.8.3 → deriva_cli-0.8.4}/deriva/adapters/nlp/translate.py

@@ -20,8 +20,7 @@ class Translator:
 
     def __init__(self, package_dir: Path):
         self.pieces = sentencepiece.SentencePieceProcessor(model_file=str(package_dir / "sentencepiece.model"))
-        # ctranslate2 imports its compiled classes inside a try block, which ty reads as possibly missing
-        self.model = ctranslate2.Translator(str(package_dir / "model"), device="cpu", inter_threads=4, intra_threads=1)  # ty: ignore[possibly-missing-attribute]
+        self.model = ctranslate2.Translator(str(package_dir / "model"), device="cpu", inter_threads=4, intra_threads=1)
 
     def translate(self, texts: list[str], settings: Settings) -> dict[str, str]:
         """Each text on its own (batch size 1), so a translation never depends on the other texts."""