aria-code 0.52.0__py3-none-any.whl

aria_code/packages/aria_services/context_checkpoints.py

@@ -0,0 +1,157 @@
+"""Compaction checkpoints — persist the pre-compaction conversation.
+
+Resolves the context layer's long-standing blocker (artifact schema and
+retention policy, decided 2026-07): every compaction first appends a
+full-snapshot checkpoint, so the conversation state that compaction is about
+to destroy becomes restorable instead of gone.
+
+Schema  ``aria.context_checkpoint.v1`` — one JSON object per line:
+    schema, ts, session_id, seq, kind ("compact" | "hard" | "fallback"),
+    message_count, truncated, envelope (optional compaction metadata),
+    messages (the full pre-compaction conversation; oldest messages dropped
+    first if the serialized snapshot would exceed the per-record byte cap).
+
+Storage  ``<root>/<session_id>.jsonl`` (append-only, crash-safe, greppable —
+same conventions as the session JSONL store and the durable run store).
+
+Retention (enforced on every write, config-overridable by the caller):
+    keep the newest ``keep_per_session`` records per session, and delete
+    sibling session files untouched for ``max_age_days``.
+
+Pure besides filesystem writes under ``root``; clock injectable for tests.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+from aria_code.packages.aria_core.paths import aria_home
+
+CHECKPOINT_SCHEMA = "aria.context_checkpoint.v1"
+DEFAULT_KEEP_PER_SESSION = 5
+DEFAULT_MAX_AGE_DAYS = 30
+DEFAULT_MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024
+
+
+class ContextCheckpointStore:
+    def __init__(
+        self,
+        root: Path,
+        *,
+        keep_per_session: int = DEFAULT_KEEP_PER_SESSION,
+        max_age_days: int = DEFAULT_MAX_AGE_DAYS,
+        max_snapshot_bytes: int = DEFAULT_MAX_SNAPSHOT_BYTES,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self.root = Path(root)
+        self.keep_per_session = max(1, int(keep_per_session))
+        self.max_age_days = max(1, int(max_age_days))
+        self.max_snapshot_bytes = max(64 * 1024, int(max_snapshot_bytes))
+        self.clock = clock
+
+    # ── write path ───────────────────────────────────────────────────────────
+
+    def record(
+        self,
+        session_id: str,
+        messages: List[dict],
+        *,
+        kind: str = "compact",
+        envelope: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Append one checkpoint for *session_id*; returns the written record."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        existing = self.list(session_id)
+        seq = (existing[-1]["seq"] + 1) if existing else 1
+
+        snapshot, truncated = self._bounded_snapshot(list(messages or []))
+        record = {
+            "schema": CHECKPOINT_SCHEMA,
+            "ts": self.clock(),
+            "session_id": str(session_id),
+            "seq": seq,
+            "kind": kind,
+            "message_count": len(messages or []),
+            "truncated": truncated,
+            "envelope": dict(envelope) if envelope else {},
+            "messages": snapshot,
+        }
+
+        kept = (existing + [record])[-self.keep_per_session:]
+        path = self._path(session_id)
+        tmp = path.with_suffix(".jsonl.tmp")
+        tmp.write_text(
+            "".join(json.dumps(r, ensure_ascii=False, default=str) + "\n" for r in kept),
+            encoding="utf-8",
+        )
+        tmp.replace(path)
+        self._expire_old_files()
+        return record
+
+    def _bounded_snapshot(self, messages: List[dict]) -> tuple:
+        """Drop oldest messages until the serialized snapshot fits the cap."""
+        truncated = False
+        while messages:
+            blob = json.dumps(messages, ensure_ascii=False, default=str)
+            if len(blob.encode("utf-8")) <= self.max_snapshot_bytes:
+                return messages, truncated
+            drop = max(1, len(messages) // 10)
+            messages = messages[drop:]
+            truncated = True
+        return [], truncated
+
+    def _expire_old_files(self) -> None:
+        cutoff = self.clock() - self.max_age_days * 86400
+        try:
+            for f in self.root.glob("*.jsonl"):
+                if f.stat().st_mtime < cutoff:
+                    f.unlink(missing_ok=True)
+        except Exception:
+            pass  # retention is best-effort; never break the write path
+
+    # ── read path ────────────────────────────────────────────────────────────
+
+    def list(self, session_id: str) -> List[Dict[str, Any]]:
+        path = self._path(session_id)
+        if not path.exists():
+            return []
+        records: List[Dict[str, Any]] = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(obj, dict) and obj.get("schema") == CHECKPOINT_SCHEMA:
+                records.append(obj)
+        return records
+
+    def latest(self, session_id: str) -> Optional[Dict[str, Any]]:
+        records = self.list(session_id)
+        return records[-1] if records else None
+
+    @staticmethod
+    def restore_messages(record: Dict[str, Any]) -> List[dict]:
+        """The conversation as it stood before that compaction."""
+        msgs = record.get("messages")
+        return [dict(m) for m in msgs] if isinstance(msgs, list) else []
+
+    def _path(self, session_id: str) -> Path:
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in str(session_id)) or "session"
+        return self.root / f"{safe}.jsonl"
+
+
+def default_checkpoint_root() -> Path:
+    """Same home-resolution rule as the durable run store."""
+    import os
+    configured = os.getenv("ARIA_HOME")
+    if configured:
+        root = Path(configured).expanduser()
+    else:
+        legacy = aria_home()
+        root = legacy if legacy.exists() else Path.home() / ".aria-code"
+    return root / "runtime" / "context_checkpoints"

aria_code/packages/aria_services/data.py

@@ -0,0 +1,11 @@
+"""Data service facade for package-level imports."""
+
+from __future__ import annotations
+
+from aria_code.data_service import DataBundle, DataService, DataServiceResult
+
+__all__ = [
+    "DataBundle",
+    "DataService",
+    "DataServiceResult",
+]

aria_code/packages/aria_services/provider_health.py

@@ -0,0 +1,268 @@
+"""Provider error classification and lightweight health state."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, List
+
+
+@dataclass(frozen=True)
+class ProviderIssue:
+    provider: str
+    category: str
+    message: str
+    retryable: bool = True
+    cooldown_seconds: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ProviderState:
+    provider: str
+    status: str = "ok"
+    last_error_category: str = ""
+    last_error: str = ""
+    failures: int = 0
+    cooldown_until: float = 0.0
+    last_seen_at: float = 0.0
+    last_success_at: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["cooldown_active"] = self.cooldown_until > time.time()
+        data["cooldown_remaining_seconds"] = max(0, int(self.cooldown_until - time.time()))
+        return data
+
+
+@dataclass(frozen=True)
+class ProviderHealthSummary:
+    schema: str
+    total: int
+    ok: int
+    warn: int
+    err: int
+    cooldown: int
+    auth_errors: int
+    providers: List[str]
+    status: str
+    detail: str
+    suggestion: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+_PUBLIC_SERVICE_LABELS = {
+    "market_data": "市场数据",
+    "ai": "AI 助手",
+}
+
+
+@dataclass(frozen=True)
+class PublicServiceStatus:
+    """A safe, product-facing view of internal provider health."""
+
+    schema: str
+    service: str
+    state: str
+    label: str
+    message: str
+    can_retry: bool
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def public_service_status(
+    service: str, snapshot: List[Dict[str, Any]] | None = None
+) -> PublicServiceStatus:
+    """Project provider health into copy that is safe to render in the product.
+
+    Provider names, endpoint details and raw failures remain internal diagnostics.
+    """
+
+    service_key = str(service or "").strip().lower() or "service"
+    label = _PUBLIC_SERVICE_LABELS.get(service_key, "服务")
+    rows = list(snapshot or [])
+
+    if not rows:
+        return PublicServiceStatus(
+            schema="aria.public_service_status.v1",
+            service=service_key,
+            state="unknown",
+            label=label,
+            message=f"{label}状态将在首次使用后更新。",
+            can_retry=False,
+        )
+
+    states = [str(row.get("status") or "unknown") for row in rows]
+    categories = [str(row.get("last_error_category") or "") for row in rows]
+    available_count = sum(state == "ok" for state in states)
+
+    if available_count == len(rows):
+        state, message, can_retry = "available", f"{label}可用。", False
+    elif available_count:
+        state, message, can_retry = (
+            "degraded",
+            f"{label}已自动切换到可用服务。",
+            True,
+        )
+    elif "auth" in categories:
+        state, message, can_retry = (
+            "unavailable",
+            f"{label}暂不可用，需要检查连接设置。",
+            False,
+        )
+    else:
+        state, message, can_retry = "unavailable", f"{label}暂不可用，请稍后重试。", True
+
+    return PublicServiceStatus(
+        schema="aria.public_service_status.v1",
+        service=service_key,
+        state=state,
+        label=label,
+        message=message,
+        can_retry=can_retry,
+    )
+
+
+def classify_provider_error(provider: str, error: Any) -> ProviderIssue:
+    text = str(error or "").strip()
+    low = text.lower()
+    if not text:
+        return ProviderIssue(provider, "unavailable", "provider returned no usable data", True, 30)
+    if any(token in low for token in ("429", "rate", "too many", "limit")):
+        return ProviderIssue(provider, "rate_limited", "provider rate limited the request", True, 60)
+    if any(token in low for token in ("timeout", "timed out", "curl: (28)", "read timed out")):
+        return ProviderIssue(provider, "timeout", "provider request timed out", True, 30)
+    if any(token in low for token in ("connection", "network", "refused", "remote", "dns", "name resolution")):
+        return ProviderIssue(provider, "network", "provider network connection failed", True, 30)
+    if any(token in low for token in ("empty", "no data", "not found", "none", "null")):
+        return ProviderIssue(provider, "no_data", "provider returned no market data", True, 15)
+    if any(token in low for token in ("unauthorized", "forbidden", "api key", "401", "403")):
+        return ProviderIssue(provider, "auth", "provider authentication failed", False, 0)
+    # Do not retain raw provider errors here. They can contain URLs, request
+    # headers, or tokens and this state is consumed by product diagnostics.
+    return ProviderIssue(provider, "error", "provider request failed", True, 30)
+
+
+class ProviderHealthRegistry:
+    """In-process health state for data providers."""
+
+    def __init__(self) -> None:
+        self._states: Dict[str, ProviderState] = {}
+
+    def mark_success(self, provider: str) -> None:
+        if not provider:
+            return
+        state = self._states.setdefault(provider, ProviderState(provider=provider))
+        state.status = "ok"
+        state.last_error_category = ""
+        state.last_error = ""
+        state.failures = 0
+        state.cooldown_until = 0.0
+        now = time.time()
+        state.last_seen_at = now
+        state.last_success_at = now
+
+    def mark_issue(self, issue: ProviderIssue) -> None:
+        if not issue.provider:
+            return
+        state = self._states.setdefault(issue.provider, ProviderState(provider=issue.provider))
+        now = time.time()
+        state.status = issue.category
+        state.last_error_category = issue.category
+        state.last_error = issue.message
+        state.failures += 1
+        state.last_seen_at = now
+        if issue.cooldown_seconds:
+            state.cooldown_until = max(state.cooldown_until, now + issue.cooldown_seconds)
+
+    def provider_in_cooldown(self, provider: str) -> bool:
+        state = self._states.get(provider)
+        return bool(state and state.cooldown_until > time.time())
+
+    def snapshot(self) -> List[Dict[str, Any]]:
+        return [self._states[name].to_dict() for name in sorted(self._states)]
+
+    def summary(self) -> ProviderHealthSummary:
+        return summarize_provider_health(self.snapshot())
+
+    def public_status(self, service: str) -> PublicServiceStatus:
+        return public_service_status(service, self.snapshot())
+
+
+GLOBAL_PROVIDER_HEALTH = ProviderHealthRegistry()
+
+
+def summarize_provider_health(snapshot: List[Dict[str, Any]] | None = None) -> ProviderHealthSummary:
+    rows = list(snapshot or [])
+    if not rows:
+        return ProviderHealthSummary(
+            schema="aria.provider_health_summary.v1",
+            total=0,
+            ok=0,
+            warn=0,
+            err=0,
+            cooldown=0,
+            auth_errors=0,
+            providers=[],
+            status="warn",
+            detail="no provider calls recorded in this session",
+            suggestion="Run /quote, /ta, /analyze, or /report to populate provider health.",
+        )
+
+    ok = warn = err = cooldown = auth_errors = 0
+    providers: list[str] = []
+    for row in rows:
+        provider = str(row.get("provider") or "provider")
+        providers.append(provider)
+        status = str(row.get("status") or "unknown")
+        error_category = str(row.get("last_error_category") or "")
+        if status == "ok":
+            ok += 1
+        elif error_category == "auth":
+            err += 1
+            auth_errors += 1
+        else:
+            warn += 1
+        if row.get("cooldown_active"):
+            cooldown += 1
+
+    if err:
+        status = "err"
+    elif warn or cooldown:
+        status = "warn"
+    else:
+        status = "ok"
+
+    parts = [f"{len(rows)} providers"]
+    if ok:
+        parts.append(f"{ok} ok")
+    if warn:
+        parts.append(f"{warn} warn")
+    if err:
+        parts.append(f"{err} err")
+    if cooldown:
+        parts.append(f"{cooldown} cooldown")
+
+    suggestion = "Run /doctor --network or inspect /apikey." if status != "ok" else "All providers healthy."
+    if auth_errors:
+        suggestion = "Fix API keys first, then retry /doctor or /cloud health."
+
+    return ProviderHealthSummary(
+        schema="aria.provider_health_summary.v1",
+        total=len(rows),
+        ok=ok,
+        warn=warn,
+        err=err,
+        cooldown=cooldown,
+        auth_errors=auth_errors,
+        providers=providers,
+        status=status,
+        detail=", ".join(parts),
+        suggestion=suggestion,
+    )

aria_code/packages/aria_services/references.py

@@ -0,0 +1,247 @@
+"""Typed, read-only ``@`` context references for Aria inputs.
+
+``/`` selects an operation. ``@`` selects context for that operation or for a
+natural-language request.  This service deliberately has no terminal or LLM
+dependency so the CLI, SDK, and future clients share the same semantics.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Iterator, Sequence
+
+
+@dataclass(frozen=True)
+class ReferenceKind:
+    name: str
+    label_en: str
+    label_zh: str
+    filesystem: bool = False
+
+
+REFERENCE_KINDS: tuple[ReferenceKind, ...] = (
+    ReferenceKind("file", "File", "文件", filesystem=True),
+    ReferenceKind("folder", "Folder", "目录", filesystem=True),
+    ReferenceKind("asset", "Market asset", "市场资产"),
+    ReferenceKind("portfolio", "Portfolio", "投资组合", filesystem=True),
+    ReferenceKind("strategy", "Strategy", "策略", filesystem=True),
+    ReferenceKind("dataset", "Dataset", "数据集", filesystem=True),
+    ReferenceKind("run", "Research run", "研究运行", filesystem=True),
+    ReferenceKind("report", "Report", "报告", filesystem=True),
+)
+
+_KIND_MAP = {item.name: item for item in REFERENCE_KINDS}
+_REF_RE = re.compile(
+    r"(?<![\w@])@(?:(?P<kind>[A-Za-z][A-Za-z0-9_-]*):)?"
+    r"(?P<value>\"[^\"\n]+\"|'[^'\n]+'|[^\s@]+)"
+)
+_TRAILING_PUNCTUATION = ",;!?，。；！？)]}"
+_ASSET_RE = re.compile(r"^[A-Za-z0-9^._=-]{1,32}$")
+_RESOURCE_DIRS = {
+    "portfolio": ("portfolios",),
+    "strategy": ("strategies",),
+    "dataset": ("datasets", "data"),
+    "run": ("runs", "reports"),
+    "report": ("reports", "generated"),
+}
+_RESOURCE_EXTENSIONS = ("", ".md", ".json", ".yaml", ".yml", ".toml", ".csv", ".html")
+
+
+def reference_search_roots(kind: str, workspace: Path, output_root: Path | None = None) -> tuple[Path, ...]:
+    """Return deterministic search roots used by resolution and completion."""
+    roots: list[Path] = []
+    for name in _RESOURCE_DIRS.get(kind, ()):
+        roots.extend((workspace / ".aria" / name, workspace / name))
+        if output_root:
+            roots.append(output_root / name)
+    return tuple(dict.fromkeys(roots))
+
+
+@dataclass(frozen=True)
+class ReferencePolicy:
+    workspace: Path = field(default_factory=Path.cwd)
+    output_root: Path | None = None
+    allowed_roots: tuple[Path, ...] = ()
+
+    def normalized(self) -> "ReferencePolicy":
+        workspace = self.workspace.expanduser().resolve()
+        output_root = self.output_root.expanduser().resolve() if self.output_root else None
+        roots = [workspace]
+        if output_root:
+            roots.append(output_root)
+        roots.extend(path.expanduser().resolve() for path in self.allowed_roots)
+        return ReferencePolicy(
+            workspace=workspace,
+            output_root=output_root,
+            allowed_roots=tuple(dict.fromkeys(roots)),
+        )
+
+
+@dataclass(frozen=True)
+class ContextReference:
+    raw: str
+    kind: str
+    value: str
+    start: int
+    end: int
+    resolved_value: str = ""
+    path: Path | None = None
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return not self.error
+
+
+@dataclass(frozen=True)
+class PreparedReferences:
+    original_text: str
+    expanded_text: str
+    context_block: str
+    references: tuple[ContextReference, ...]
+
+    @property
+    def errors(self) -> tuple[ContextReference, ...]:
+        return tuple(ref for ref in self.references if ref.error)
+
+    @property
+    def prompt(self) -> str:
+        if not self.context_block:
+            return self.expanded_text
+        return f"{self.expanded_text}\n\n{self.context_block}"
+
+
+def iter_reference_tokens(text: str) -> Iterator[tuple[str, str, str, int, int]]:
+    """Yield ``(raw, kind, value, start, end)`` while ignoring email addresses."""
+    for match in _REF_RE.finditer(text):
+        kind = (match.group("kind") or "file").lower()
+        token = match.group("value")
+        end = match.end()
+        if token[:1] in {"\"", "'"} and token[-1:] == token[:1]:
+            value = token[1:-1]
+        else:
+            trailing = _TRAILING_PUNCTUATION + ("." if kind not in {"file", "folder"} else "")
+            value = token.rstrip(trailing)
+            end -= len(token) - len(value)
+        if value:
+            yield text[match.start():end], kind, value, match.start(), end
+
+
+class ReferenceService:
+    """Resolve and prepare explicit context references without side effects."""
+
+    def __init__(self, policy: ReferencePolicy | None = None):
+        self.policy = (policy or ReferencePolicy()).normalized()
+
+    def prepare(self, text: str) -> PreparedReferences:
+        refs = tuple(self._resolve(*token) for token in iter_reference_tokens(text))
+        expanded = text
+        for ref in reversed(refs):
+            if not ref.ok:
+                continue
+            replacement = self._replacement(ref)
+            expanded = expanded[:ref.start] + replacement + expanded[ref.end:]
+
+        blocks: list[str] = []
+        for ref in refs:
+            if not ref.ok:
+                continue
+            target = str(ref.path) if ref.path is not None else ref.resolved_value
+            if ref.kind == "folder":
+                action = "Inspect on demand with list_files or search_code."
+            elif ref.kind == "asset":
+                action = "Fetch on demand with get_market_data or get_market_history."
+            else:
+                action = "Inspect on demand with read_file or analyze_file."
+            blocks.append(f"- {ref.kind}: {target}\n  {action}")
+
+        context_block = ""
+        if blocks:
+            context_block = (
+                "[Aria resource references - pointers only]\n"
+                "No resource content is preloaded. Use the named tools before answering.\n"
+                + "\n".join(blocks)
+                + "\n[End Aria resource references]"
+            )
+        return PreparedReferences(text, expanded, context_block, refs)
+
+    def _resolve(self, raw: str, kind: str, value: str, start: int, end: int) -> ContextReference:
+        if kind not in _KIND_MAP:
+            valid = ", ".join(item.name for item in REFERENCE_KINDS)
+            return ContextReference(raw, kind, value, start, end, error=f"unknown reference type '{kind}' (use: {valid})")
+        if kind == "asset":
+            if not _ASSET_RE.fullmatch(value):
+                return ContextReference(raw, kind, value, start, end, error=f"invalid market asset '{value}'")
+            return ContextReference(raw, kind, value, start, end, resolved_value=value.upper())
+
+        path = self._resolve_path(kind, value)
+        if path is None:
+            return ContextReference(raw, kind, value, start, end, error=f"{kind} not found: {value}")
+        if not self._is_allowed(path):
+            return ContextReference(raw, kind, value, start, end, path=path, error=f"reference is outside the allowed workspace: {value}")
+        if kind == "folder" and not path.is_dir():
+            return ContextReference(raw, kind, value, start, end, path=path, error=f"folder not found: {value}")
+        if kind != "folder" and not path.is_file():
+            return ContextReference(raw, kind, value, start, end, path=path, error=f"{kind} is not a file: {value}")
+
+        return ContextReference(
+            raw, kind, value, start, end,
+            resolved_value=str(path), path=path,
+        )
+
+    def _resolve_path(self, kind: str, value: str) -> Path | None:
+        if kind in {"file", "folder"}:
+            candidate = Path(os.path.expandvars(value)).expanduser()
+            if not candidate.is_absolute():
+                candidate = self.policy.workspace / candidate
+            try:
+                return candidate.resolve()
+            except OSError:
+                return None
+
+        for root in self._resource_roots(kind):
+            for suffix in _RESOURCE_EXTENSIONS:
+                candidate = root / f"{value}{suffix}"
+                if candidate.exists():
+                    return candidate.resolve()
+            if not root.is_dir():
+                continue
+            target_names = {value.lower(), *(f"{value}{suffix}".lower() for suffix in _RESOURCE_EXTENSIONS if suffix)}
+            seen = 0
+            for candidate in root.rglob("*"):
+                seen += 1
+                if seen > 2_000:
+                    break
+                if candidate.is_file() and (candidate.name.lower() in target_names or candidate.stem.lower() == value.lower()):
+                    return candidate.resolve()
+        return None
+
+    def _resource_roots(self, kind: str) -> Iterable[Path]:
+        yield from reference_search_roots(kind, self.policy.workspace, self.policy.output_root)
+
+    def _is_allowed(self, path: Path) -> bool:
+        resolved = path.resolve()
+        return any(resolved == root or root in resolved.parents for root in self.policy.allowed_roots)
+
+    def _replacement(self, ref: ContextReference) -> str:
+        if ref.kind == "asset":
+            return ref.resolved_value
+        if ref.path is not None:
+            return shlex.quote(str(ref.path)) if " " in str(ref.path) else str(ref.path)
+        return ref.resolved_value
+
+def build_reference_service(
+    *,
+    workspace: Path | None = None,
+    output_root: Path | None = None,
+    allowed_roots: Sequence[Path] = (),
+) -> ReferenceService:
+    return ReferenceService(ReferencePolicy(
+        workspace=workspace or Path.cwd(),
+        output_root=output_root,
+        allowed_roots=tuple(allowed_roots),
+    ))