synaptane 1.0.0rc2__py3-none-any.whl

synaptane/__init__.py

@@ -0,0 +1,53 @@
+"""Synaptane: a team second brain stored in Git."""
+
+import os
+import re
+import subprocess
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+try:
+    __version__ = version("synaptane")
+except PackageNotFoundError:  # running from the sources without installing
+    __version__ = "0+unknown"
+
+UNKNOWN_COMMIT = "unknown"
+
+
+@cache
+def git_commit() -> str:
+    """Commit the running code comes from, to know afterwards which version did what.
+
+    The version number (`1.0.0rc1`) is the same for every commit between two releases:
+    only the commit tells two deployments apart. In the image, it is written at build time
+    (`--build-arg GIT_SHA=…` → `SYNAPTANE_GIT_SHA`); from the sources, it is asked of the
+    repository that contains this package. Otherwise: "unknown", never an error.
+    """
+    sha = os.environ.get("SYNAPTANE_GIT_SHA", "").strip()
+    if sha and sha != "unknown":  # "unknown": image built without the GIT_SHA argument
+        return sha
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", "--quiet", "HEAD"],
+            cwd=Path(__file__).parent,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):  # git missing, unreadable folder…
+        return UNKNOWN_COMMIT
+    sha = result.stdout.strip()
+    return sha if result.returncode == 0 and sha else UNKNOWN_COMMIT
+
+
+def short_commit() -> str:
+    """The first 7 characters of a SHA (like GitHub), or the value as is."""
+    sha = git_commit()
+    return sha[:7] if re.fullmatch(r"[0-9a-f]{8,64}", sha) else sha
+
+
+def version_label() -> str:
+    """`1.0.0rc1 (abc1234)`: what `--version`, `doctor` and the administration show."""
+    return f"{__version__} ({short_commit()})"

synaptane/__main__.py

@@ -0,0 +1,3 @@
+from synaptane.cli import main
+
+raise SystemExit(main())

synaptane/ai/__init__.py

@@ -0,0 +1 @@
+"""AI providers: a tool-driven conversation, whatever the provider."""

synaptane/ai/anthropic_provider.py

@@ -0,0 +1,160 @@
+"""Claude through the official `anthropic` SDK (manual tool loop, shared by all providers).
+
+- Adaptive thinking by default on recent models; depth set by `effort`.
+- Server-side fallback (`fallbacks: "default"`): if a request is refused by a safety filter,
+  the API replays it on a fallback model instead of failing.
+- The history is kept as is (response blocks sent back in full).
+- Strict tools (`strict: true`) when the model accepts them: the schemas are closed.
+"""
+
+from typing import Any, cast
+
+import anthropic
+from anthropic.types.beta import BetaMessageParam, BetaOutputConfigParam, BetaToolParam
+
+from synaptane.ai.base import AIConfig, AIError, ToolCall, ToolResult, ToolSpec, Turn
+
+MAX_TOKENS = 16000
+FALLBACK_BETA = "server-side-fallback-2026-07-01"
+# Server-side fallback: only these models, and only on the Claude API itself.
+FALLBACK_MODELS = ("claude-opus-5-5", "claude-opus-5", "claude-fable-5-1", "claude-sonnet-5-5")
+NO_EFFORT_MODELS = ("claude-haiku",)  # `effort` refused
+
+
+def request_options(config: AIConfig) -> dict[str, Any]:
+    """Claude-specific parameters, depending on the model and the endpoint (gateway or not)."""
+    model = config.model.strip().lower()
+    options: dict[str, Any] = {}
+    if not model.startswith(NO_EFFORT_MODELS):
+        options["output_config"] = cast(BetaOutputConfigParam, {"effort": config.effort})
+    if not config.base_url and any(
+        model == m or model.startswith(m + "-") for m in FALLBACK_MODELS
+    ):
+        options["betas"] = [FALLBACK_BETA]
+        options["fallbacks"] = "default"
+    return options
+
+
+# Strict tools (arguments always match the schema): models that accept them.
+STRICT_MODELS = (
+    "claude-fable-5",
+    "claude-mythos-5",
+    "claude-opus-5",
+    "claude-opus-4-8",
+    "claude-sonnet-5",
+    "claude-haiku-4-5",
+)
+
+
+def _closed(schema: object) -> bool:
+    """Every object of the schema is closed (`additionalProperties: false`), a condition of
+    strict mode; otherwise the API would refuse the request."""
+    if isinstance(schema, dict):
+        if schema.get("type") == "object" and schema.get("additionalProperties") is not False:
+            return False
+        return all(_closed(v) for v in schema.values())
+    if isinstance(schema, list):
+        return all(_closed(v) for v in schema)
+    return True
+
+
+def tool_param(config: AIConfig, tool: ToolSpec) -> BetaToolParam:
+    """Tool definition for the API. `strict: true` guarantees valid arguments (no invented
+    parameter, no wrong type): only on the Claude API itself (a gateway may not know it), for
+    a model that accepts it and a closed schema."""
+    param: BetaToolParam = {
+        "name": tool.name,
+        "description": tool.description,
+        "input_schema": tool.input_schema,
+    }
+    model = config.model.strip().lower()
+    if not config.base_url and model.startswith(STRICT_MODELS) and _closed(tool.input_schema):
+        param["strict"] = True
+    return param
+
+
+class AnthropicConversation:
+    def __init__(
+        self, config: AIConfig, system: str, first_message: str, tools: list[ToolSpec]
+    ) -> None:
+        self.config = config
+        self.client = anthropic.Anthropic(
+            api_key=config.api_key, base_url=config.base_url or None, max_retries=3
+        )
+        self.system = system
+        self.tools = [tool_param(config, t) for t in tools]
+        self.messages: list[BetaMessageParam] = [{"role": "user", "content": first_message}]
+
+    def step(self) -> Turn:
+        try:
+            response = self.client.beta.messages.create(
+                model=self.config.model,
+                max_tokens=MAX_TOKENS,
+                system=self.system,
+                tools=self.tools,
+                messages=self.messages,
+                **request_options(self.config),
+                # Append-only history: each turn reads the previous one back from the cache.
+                cache_control={"type": "ephemeral"},
+            )
+        except (anthropic.AuthenticationError, anthropic.PermissionDeniedError) as error:
+            raise AIError("Anthropic key refused: {detail}", detail=error.message) from None
+        except anthropic.NotFoundError as error:
+            raise AIError(
+                "Model not found ({model}): {detail}", model=self.config.model, detail=error.message
+            ) from None
+        except anthropic.BadRequestError as error:
+            raise AIError("Request refused by Anthropic: {detail}", detail=error.message) from None
+        except anthropic.RateLimitError:
+            raise AIError("Anthropic rate limit reached.", transient=True) from None
+        except anthropic.APIStatusError as error:
+            transient = error.status_code >= 500
+            raise AIError(
+                "Anthropic error {status}", transient=transient, status=error.status_code
+            ) from None
+        except anthropic.APIConnectionError:
+            raise AIError("Anthropic unreachable.", transient=True) from None
+
+        # Append-only history: the full content is sent back on the next turn.
+        self.messages.append({"role": "assistant", "content": response.content})
+        calls = [
+            ToolCall(block.id, block.name, dict(block.input))
+            for block in response.content
+            if block.type == "tool_use"
+        ]
+        text = "".join(block.text for block in response.content if block.type == "text")
+        stop = {
+            "tool_use": "tool_use",
+            "max_tokens": "max_tokens",
+            "refusal": "refusal",
+        }.get(str(response.stop_reason), "end")
+        if calls and stop == "end":
+            stop = "tool_use"  # a truncation (max_tokens) or a refusal stays visible
+        # Cache writes: counted in the input, and separately for their higher price
+        # (1.25 × the input with the 5-minute duration of automatic caching).
+        written = response.usage.cache_creation_input_tokens or 0
+        return Turn(
+            text=text,
+            tool_calls=calls,
+            stop=stop,  # type: ignore[arg-type]
+            input_tokens=response.usage.input_tokens + written,
+            output_tokens=response.usage.output_tokens,
+            cached_tokens=response.usage.cache_read_input_tokens or 0,
+            cache_write_tokens=written,
+        )
+
+    def reply(self, results: list[ToolResult]) -> None:
+        # All results of a turn in a single user message.
+        content: list[Any] = [
+            {
+                "type": "tool_result",
+                "tool_use_id": r.call_id,
+                "content": r.content,
+                "is_error": r.is_error,
+            }
+            for r in results
+        ]
+        self.messages.append({"role": "user", "content": content})
+
+    def nudge(self, text: str) -> None:
+        self.messages.append({"role": "user", "content": text})

synaptane/ai/base.py

@@ -0,0 +1,137 @@
+"""Common provider interface: a conversation that moves forward in tool turns."""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+from synaptane.ai import quota
+from synaptane.core.errors import Label
+
+API_PROVIDERS = ("anthropic", "openai", "mistral", "ollama", "openai_compatible")
+# Subscriptions: the official CLI, logged in on the server, runs the agent (cli_agents).
+SUBSCRIPTION_PROVIDERS = ("claude_code", "codex")
+PROVIDERS = API_PROVIDERS + SUBSCRIPTION_PROVIDERS
+KEYLESS_PROVIDERS = ("ollama", "openai_compatible", *SUBSCRIPTION_PROVIDERS)
+EFFORTS = ("low", "medium", "high", "xhigh", "max")
+
+DEFAULT_MODELS: dict[str, str] = {
+    "anthropic": "claude-sonnet-5-5",  # tidy-up: good value for money
+    "mistral": "mistral-large-latest",
+}
+DEFAULT_BASE_URLS: dict[str, str] = {
+    "openai": "https://api.openai.com/v1",
+    "mistral": "https://api.mistral.ai/v1",
+    "ollama": "http://localhost:11434/v1",
+}
+
+
+class AIError(Exception):
+    """Failed call to the provider. `transient`: retrying later makes sense. `usage`: what was
+    consumed before the failure (a CLI that ends in error may have worked and used up quota):
+    it must be counted anyway. `label`: the message to translate (English template and
+    `params`); `str(error)` is the English text."""
+
+    def __init__(
+        self,
+        template: str,
+        *,
+        transient: bool = False,
+        usage: "Usage | None" = None,
+        **params: object,
+    ) -> None:
+        self.label = Label(template, **params)
+        super().__init__(str(self.label))
+        self.transient = transient
+        self.usage = usage
+
+
+@dataclass(frozen=True)
+class AIConfig:
+    provider: str
+    model: str
+    api_key: str = ""
+    base_url: str = ""
+    effort: str = "medium"  # Claude only: reasoning depth
+
+    @property
+    def endpoint(self) -> str:
+        return (self.base_url or DEFAULT_BASE_URLS.get(self.provider, "")).rstrip("/")
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class Turn:
+    text: str
+    tool_calls: list[ToolCall]
+    stop: Literal["end", "tool_use", "max_tokens", "refusal"]
+    input_tokens: int = 0  # input billed at full price (cache writes included)
+    output_tokens: int = 0
+    cached_tokens: int = 0  # input read back from the cache
+    cache_write_tokens: int = 0  # share of `input_tokens` written to the cache (higher price)
+
+
+@dataclass
+class ToolResult:
+    call_id: str
+    content: str
+    is_error: bool = False
+
+
+@dataclass
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cached_tokens: int = 0
+    cache_write_tokens: int = 0  # share of `input_tokens` written to the cache (higher price)
+    turns: int = 0
+    notes: list[str] = field(default_factory=list)
+    quota: dict[str, Any] | None = None  # subscription: used share of the windows (ai.quota)
+
+    def add(self, turn: Turn) -> None:
+        self.input_tokens += turn.input_tokens
+        self.output_tokens += turn.output_tokens
+        self.cached_tokens += turn.cached_tokens
+        self.cache_write_tokens += turn.cache_write_tokens
+        self.turns += 1
+
+    def merge(self, other: "Usage") -> None:
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.cached_tokens += other.cached_tokens
+        self.cache_write_tokens += other.cache_write_tokens
+        self.turns += other.turns
+        self.notes.extend(other.notes)
+        self.quota = quota.merge(self.quota, other.quota)
+
+    @property
+    def total(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def weighted(self) -> int:
+        """Weighted tokens for the caps: input read back from the cache counts for a tenth."""
+        return self.input_tokens + self.output_tokens + self.cached_tokens // 10
+
+
+class Conversation(Protocol):
+    """Provider-native history: `step` asks for a turn, `reply` answers it."""
+
+    def step(self) -> Turn: ...
+
+    def reply(self, results: list[ToolResult]) -> None: ...
+
+    def nudge(self, text: str) -> None:
+        """Prods the agent with a message (e.g. it stopped without calling a tool)."""
+        ...