generic-ml-cache-core 0.2.0__py3-none-any.whl

generic_ml_cache_core/application/domain/model/identity/api_call_identity.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ApiCallIdentity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.common.checksum import checksum_input_data
+
+
+@dataclass(frozen=True)
+class ApiCallIdentity(CallIdentity):
+    """The identity of a direct API call.
+
+    Addressed by provider, model, and a fingerprint of the full message list —
+    the raw messages may carry sensitive context and are never keyed or stored,
+    only their digest. The kind is folded into the key, so an API call can never
+    collide with a local managed or passthrough call.
+    """
+
+    provider: str
+    model: str
+    messages_fingerprint: str
+
+    def generate_key(self) -> str:
+        return checksum_input_data(
+            {
+                "kind": ExecutionKind.API.value,
+                "provider": self.provider,
+                "model": self.model,
+                "messages": self.messages_fingerprint,
+            }
+        )

generic_ml_cache_core/application/domain/model/identity/call_identity.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CallIdentity."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class CallIdentity(ABC):
+    """The value object that determines an execution's cache key.
+
+    Polymorphic: each execution kind determines its key from different fields
+    (a managed call from fingerprints of model/prompt/files; a passthrough call
+    from its opaque native args; an API call from its provider and messages). The
+    aggregate is addressed by ``generate_key``; every implementation folds its
+    kind into the key, so identities of different kinds can never collide.
+    """
+
+    @abstractmethod
+    def generate_key(self) -> str:
+        """Return a stable hex digest that uniquely addresses this call.
+
+        Pure: hashes only the already-in-memory fingerprints. No I/O.
+        """

generic_ml_cache_core/application/domain/model/identity/managed_call_identity.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ManagedCallIdentity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, FrozenSet, Optional
+
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.common.checksum import checksum_input_data
+
+
+@dataclass(frozen=True)
+class ManagedCallIdentity(CallIdentity):
+    """The identity of a fully managed local call.
+
+    Holds only processed fields — by the time it is constructed, every text input
+    has been fingerprinted and every file path resolved to its content
+    fingerprint. It is not the user's raw request.
+
+    allow_paths (permission grants to scan folders) are NOT a field here: they do
+    not enter the key and travel separately to the client runner.
+    """
+
+    client: str
+    model: str
+    effort: str
+    context_fingerprint: str
+    prompt_fingerprint: str
+    input_file_fingerprints: Dict[str, str] = field(default_factory=dict)
+    client_args_fingerprint: Optional[str] = None
+    grants: FrozenSet[str] = field(default_factory=frozenset)
+
+    def generate_key(self) -> str:
+        key_data: Dict[str, str] = {
+            "kind": ExecutionKind.LOCAL_MANAGED.value,
+            "client": self.client,
+            "model": self.model,
+            "effort": self.effort,
+            "context": self.context_fingerprint,
+            "prompt": self.prompt_fingerprint,
+        }
+        # Path-sensitive: the path enters the key alongside the content fingerprint.
+        # A rename is a real change (the prompt may reference the file by name), so it
+        # must yield a new key — soundness over hit-rate (prefer a miss to a wrong hit).
+        for file_path, file_fingerprint in sorted(self.input_file_fingerprints.items()):
+            key_data[f"file:{file_path}"] = file_fingerprint
+        if self.client_args_fingerprint is not None:
+            key_data[f"args:{self.client_args_fingerprint}"] = self.client_args_fingerprint
+        if self.grants:
+            key_data["grants"] = ",".join(sorted(self.grants))
+        return checksum_input_data(key_data)

generic_ml_cache_core/application/domain/model/identity/passthrough_call_identity.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""PassthroughCallIdentity."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.common.checksum import checksum_input_data
+
+
+@dataclass(frozen=True)
+class PassthroughCallIdentity(CallIdentity):
+    """The identity of a passthrough (alias) call.
+
+    A passthrough is opaque: gmlcache does not model its inputs, only forwards the
+    native argument tail to the client. So the identity is just the client plus a
+    *fingerprint* of those native args — the raw args may carry secrets and are
+    never keyed or stored, only their digest. The kind is folded into the key, so
+    a passthrough can never collide with a managed call.
+    """
+
+    client: str
+    native_args_fingerprint: str
+
+    def generate_key(self) -> str:
+        return checksum_input_data(
+            {
+                "kind": ExecutionKind.LOCAL_PASSTHROUGH.value,
+                "client": self.client,
+                "args": self.native_args_fingerprint,
+            }
+        )

generic_ml_cache_core/application/domain/model/model_info.py

@@ -0,0 +1,20 @@
+"""ModelInfo."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ModelInfo:
+    """One model a client reports it can use. Purely what the client relayed.
+
+    ``id`` is the string a caller would pass as ``--model``; ``name`` is the
+    client's own human label. ``default``/``current`` mirror any marker the
+    client printed. The cache neither invents nor validates these fields.
+    """
+
+    id: str
+    name: str
+    default: bool = False
+    current: bool = False

generic_ml_cache_core/application/domain/model/model_listing.py

@@ -0,0 +1,29 @@
+"""ModelListing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from generic_ml_cache_core.application.port.out.base import ModelInfo
+
+
+@dataclass
+class ModelListing:
+    """What discovery could learn about one client's available models.
+
+    Three honest outcomes, never a guess:
+
+    * absent client -> ``present=False`` (``supported`` is meaningless, left False);
+    * present but no listing mechanism -> ``supported=False`` with a ``reason``;
+    * present and listed -> ``supported=True`` and ``models`` populated (possibly
+      empty if the client genuinely reported none).
+
+    ``models`` is whatever the client relayed -- the cache invents nothing.
+    """
+
+    name: str
+    present: bool
+    supported: bool
+    models: Optional[List[ModelInfo]] = None
+    reason: Optional[str] = None

generic_ml_cache_core/application/domain/model/parsed_output.py

@@ -0,0 +1,23 @@
+"""ParsedOutput."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from generic_ml_cache_core.application.domain.model.usage.usage import Usage
+
+
+@dataclass(frozen=True)
+class ParsedOutput:
+    """What an adapter extracted from a client's structured output.
+
+    ``text`` is the clean answer the caller should see on stdout (the client's
+    own answer text, lifted out of its JSON wrapper). ``usage`` is the normalized
+    envelope read from the same output, or ``None`` when the client offered no
+    usage (or its output could not be parsed -- the text then falls back to the
+    raw stdout so the core call still resolves).
+    """
+
+    text: str
+    usage: Optional[Usage] = None

generic_ml_cache_core/application/domain/model/probe/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/domain/model/probe/probe_report.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ProbeReport."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.domain.model.probe.probe_status import ProbeStatus
+
+
+@dataclass(frozen=True)
+class ProbeReport:
+    """What a read-only probe forecasts for a call.
+
+    ``execution_key`` is derived for every verdict (so a caller can show the key
+    even on a miss). ``execution`` is the dehydrated current execution on a HIT —
+    present only then — carrying the queryable metadata (artifacts, usage) without
+    fetching any output bytes.
+    """
+
+    status: ProbeStatus
+    execution_key: str
+    execution: Optional[MlExecution] = None

generic_ml_cache_core/application/domain/model/probe/probe_status.py

@@ -0,0 +1,13 @@
+"""ProbeStatus."""
+
+from __future__ import annotations
+
+import enum
+
+
+class ProbeStatus(enum.Enum):
+    """The verdict of a read-only cache probe (see :func:`probe`)."""
+
+    HIT = "hit"  # a stored execution exists for this exact call
+    MISS = "miss"  # cacheable, but no execution recorded yet
+    NON_CACHEABLE = "non-cacheable"  # declares allow-path folders -> never cached

generic_ml_cache_core/application/domain/model/run/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/domain/model/run/cache_mode.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CacheMode."""
+
+from __future__ import annotations
+
+import enum
+
+
+class CacheMode(enum.Enum):
+    """Cache resolution policy for an MlExecution.
+
+    CACHE   -- serve from cache on a hit; call the client and record on a miss.
+               Default.
+    OFFLINE -- serve from cache only; a miss raises an error.
+    REFRESH -- always call the client and overwrite any existing stored output.
+    """
+
+    CACHE = "cache"
+    OFFLINE = "offline"
+    REFRESH = "refresh"

generic_ml_cache_core/application/domain/model/run/client_run_request.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ClientRunRequest."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import FrozenSet, List, Optional
+
+
+@dataclass(frozen=True)
+class ClientRunRequest:
+    """The DTO the use case constructs and passes to ClientRunnerPort.
+
+    Carries only what the client runner needs to launch the client. The
+    command's gmlcache-specific policy fields (cache_mode, persist_output,
+    scan_trust) do not appear here — they are the use case's concern, not
+    the client runner's.
+
+    input_file_paths are the declared files the client is granted read access to
+    (their content is already fingerprinted into the key); allow_paths are the
+    permission-grant folder paths the client may scan. The runner opens the
+    read-door for both; it fingerprints neither (that already happened).
+    """
+
+    client: str
+    model: str
+    effort: str
+    context: str
+    prompt: str
+    input_file_paths: List[str] = field(default_factory=list)
+    allow_paths: List[str] = field(default_factory=list)
+    client_args: List[str] = field(default_factory=list)
+    grants: FrozenSet[str] = field(default_factory=frozenset)
+    user_system_prompt: Optional[str] = None

generic_ml_cache_core/application/domain/model/run/client_run_result.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ClientRunResult and GeneratedFile."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from generic_ml_cache_core.application.domain.model.execution.execution_failure import (
+    ExecutionFailure,
+    FailureReason,
+)
+from generic_ml_cache_core.application.domain.model.execution.execution_state import ExecutionState
+from generic_ml_cache_core.application.domain.model.usage.token_usage import TokenUsage
+
+
+@dataclass(frozen=True)
+class GeneratedFile:
+    """One file the client produced, captured raw — name and bytes only.
+
+    No checksum and no blob key: storage is the use case's job, not the runner's.
+    """
+
+    name: str
+    content: bytes
+
+
+@dataclass(frozen=True)
+class ClientRunResult:
+    """The raw, transient result the ClientRunnerPort returns.
+
+    The contract surface of the runner port — not an adapter-internal type — but
+    nothing here is stored yet. The use case turns this into stored Artifacts
+    (hash each piece, put it in the blob store) and assembles the MlExecution.
+    The runner itself never hashes, never computes a key, never stores.
+
+    It also interprets its own ``exit_code`` into a run outcome — that rule reads
+    only this object's data, so it lives here, not in the use case.
+    """
+
+    exit_code: int
+    stdout: str = ""
+    stderr: str = ""
+    files: List[GeneratedFile] = field(default_factory=list)
+    #: Token accounting the runner observed (a structured client or an API), or
+    #: None when none was reported. Carried to MlExecution.token_usage by the
+    #: shared flow; not stored as output bytes (it is database-bound accounting).
+    token_usage: Optional[TokenUsage] = None
+
+    @property
+    def succeeded(self) -> bool:
+        return self.exit_code == 0
+
+    def outcome(self) -> ExecutionState:
+        return ExecutionState.SUCCESS if self.succeeded else ExecutionState.FAILED
+
+    def failure(self) -> Optional[ExecutionFailure]:
+        if self.succeeded:
+            return None
+        return ExecutionFailure(
+            reason=FailureReason.NONZERO_EXIT,
+            message=f"client exited with status {self.exit_code}",
+            exit_code=self.exit_code,
+        )

generic_ml_cache_core/application/domain/model/run/message.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Message."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Message:
+    """One message in an API call's context: a role and its content.
+
+    Provider-agnostic — the caller builds the full message list and gmlcache
+    forwards it to the provider. ``role`` is kept as a plain string because
+    providers differ on the roles they accept (system, user, assistant, tool, …).
+    """
+
+    role: str
+    content: str

generic_ml_cache_core/application/domain/model/usage/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/domain/model/usage/token_usage.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""TokenUsage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from generic_ml_cache_core.application.domain.model.usage.usage import float_or_none, int_or_none
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    """Normalized token counts for one ML execution, with the raw block kept.
+
+    Accounting data: database-bound, separate from the output artifacts.
+    Every count is Optional[int]: a value the client reported, or None when it
+    did not report that field at all. None means unknown, never zero.
+    cost_usd is the client's own advisory estimate; never derived by gmlcache.
+    raw preserves the client's verbatim usage structure losslessly.
+    """
+
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cache_read_tokens: Optional[int] = None
+    cache_write_tokens: Optional[int] = None
+    reasoning_tokens: Optional[int] = None
+    cost_usd: Optional[float] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cache_write_tokens": self.cache_write_tokens,
+            "reasoning_tokens": self.reasoning_tokens,
+            "cost_usd": self.cost_usd,
+            "raw": self.raw,
+        }
+
+    @classmethod
+    def from_dict(cls, token_usage_dict: Dict[str, Any]) -> "TokenUsage":
+        return cls(
+            input_tokens=int_or_none(token_usage_dict.get("input_tokens")),
+            output_tokens=int_or_none(token_usage_dict.get("output_tokens")),
+            cache_read_tokens=int_or_none(token_usage_dict.get("cache_read_tokens")),
+            cache_write_tokens=int_or_none(token_usage_dict.get("cache_write_tokens")),
+            reasoning_tokens=int_or_none(token_usage_dict.get("reasoning_tokens")),
+            cost_usd=float_or_none(token_usage_dict.get("cost_usd")),
+            raw=dict(token_usage_dict.get("raw", {})),
+        )

generic_ml_cache_core/application/domain/model/usage/usage.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The usage envelope: what one recorded call consumed, in a common shape.
+
+Two things live here:
+
+* :class:`Usage` -- a **normalized** token/cost envelope with a small core every
+  client fills, plus an optional ring only some report. It keeps the client's
+  **raw** usage block verbatim alongside, so nothing the client reported is lost.
+* :class:`ParsedOutput` -- what an adapter pulls out of a client's structured
+  output: the clean answer text (what the caller sees on stdout) and the
+  :class:`Usage` it read from the same output.
+
+Design rulings this encodes (do not relitigate):
+
+* **Tokens are the spine, not dollars.** Every client reports tokens; only some
+  report a dollar figure, and even that figure is the *client's own local
+  estimate* (computed from a price table bundled into the client at build time),
+  not authoritative billing. So ``cost_usd`` is advisory: recorded when offered,
+  never derived by the cache, never authoritative.
+* **Unknown is not zero.** A field the client did not report is ``None``
+  ("unknown"), never ``0``. Codex reports no cache-write count -- that is unknown,
+  not "wrote nothing". This distinction is in the type from the start because we
+  cannot anticipate what any given client (or client version, or detached/parallel
+  run) chooses to report.
+* **We record what the call reported; we do not reconstruct.** If a client
+  under-reports (e.g. subagents that billed outside the single invocation we
+  launched), that is the client's gap; we mark it unknown rather than invent a
+  total.
+* **The model the call ran under lives on the stored execution** (its ``model`` field), so
+  a reader always shows usage *next to its model* -- a Haiku token is not an Opus
+  token. The full per-model / per-subagent breakdown a client may give (e.g.
+  Claude's ``modelUsage``) is preserved in :attr:`Usage.raw`, not flattened here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+def int_or_none(value: Any) -> Optional[int]:
+    """Coerce a client-reported count to ``int``, or ``None`` if absent/unusable.
+
+    Used by adapters reading a client's JSON: a missing or non-numeric field
+    becomes ``None`` ("unknown"), never ``0``, so a value the client did not
+    report is never mistaken for a real zero.
+    """
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def float_or_none(value: Any) -> Optional[float]:
+    """Coerce a client-reported amount to ``float``, or ``None`` if absent/unusable."""
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Normalized token counts for one recorded call, with the raw block kept.
+
+    Every count is ``Optional[int]``: a value the client reported, or ``None``
+    when it did not report that count at all. ``cost_usd`` is the client's own
+    estimate in US dollars when it offered one (advisory only -- see module docs),
+    else ``None``. ``raw`` is the client's verbatim usage structure, so a caller
+    that wants a client-specific field we did not normalize can read it straight
+    from the stored execution.
+    """
+
+    #: Prompt/input tokens the call consumed.
+    input_tokens: Optional[int] = None
+    #: Generated/output tokens. For clients that fold reasoning into output
+    #: (Claude), reasoning is included here and ``reasoning_tokens`` is unknown.
+    output_tokens: Optional[int] = None
+    #: Input tokens served from the client's prompt cache (a reduced-rate read).
+    cache_read_tokens: Optional[int] = None
+    #: Input tokens spent writing new prompt-cache entries. Unknown for clients
+    #: that do not report a cache-write count (e.g. Codex).
+    cache_write_tokens: Optional[int] = None
+    #: Reasoning tokens reported *separately* from output (e.g. Codex). Unknown
+    #: when the client folds reasoning into output (Claude) or omits it (Cursor).
+    reasoning_tokens: Optional[int] = None
+    #: The client's own dollar estimate for the call, when it reports one (only
+    #: Claude does, today). Advisory, not authoritative billing; never derived.
+    cost_usd: Optional[float] = None
+    #: The client's verbatim usage structure (lossless), so unanticipated
+    #: client-specific fields stay reachable. Shape is per-client.
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cache_write_tokens": self.cache_write_tokens,
+            "reasoning_tokens": self.reasoning_tokens,
+            "cost_usd": self.cost_usd,
+            "raw": self.raw,
+        }

generic_ml_cache_core/application/domain/service/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/domain/service/cacheability.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Cacheability rule: a pure domain rule shared by every front door."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+
+def is_call_uncacheable(allow_paths: Sequence[str], scan_trust: bool) -> bool:
+    """Whether a call is non-cacheable because it declares allow-path folders.
+
+    Their contents are unbounded and cannot be fingerprinted, so the cache cannot
+    tell when they change — the call is therefore non-cacheable. ``scan_trust`` is
+    the caller's explicit override (asserting the folders are stable). This is the
+    single source of the rule, so a probe and a run can never disagree about
+    whether a given call is cacheable.
+    """
+    return bool(allow_paths) and not scan_trust

generic_ml_cache_core/application/domain/service/message_fingerprinting.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Fingerprinting of an API message list — a pure domain rule."""
+
+from __future__ import annotations
+
+from typing import Dict, Sequence
+
+from generic_ml_cache_core.application.domain.model.run.message import Message
+from generic_ml_cache_core.common.checksum import checksum_input_data
+
+
+def fingerprint_messages(messages: Sequence[Message]) -> str:
+    """Fingerprint an ordered message list into the key.
+
+    The messages may carry the user's full context (sensitive), so only their
+    digest is ever keyed or stored — never the raw content. Order is significant
+    and preserved by the positional keys; identical message lists fingerprint
+    identically.
+    """
+    data: Dict[str, str] = {}
+    for index, message in enumerate(messages):
+        data[f"{index}:role"] = message.role
+        data[f"{index}:content"] = message.content
+    return checksum_input_data(data)

generic_ml_cache_core/application/port/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/port/inbound/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""