holdspeak 0.2.1__py3-none-any.whl

holdspeak/__init__.py

@@ -0,0 +1,40 @@
+"""HoldSpeak - Voice typing for macOS and Linux. Hold, speak, release."""
+
+from __future__ import annotations
+
+
+def _resolve_version() -> str:
+    """Return the one true version.
+
+    The package metadata written from `pyproject.toml` is the single source of
+    truth. An editable install (`uv pip install -e .`) registers that metadata,
+    so this resolves correctly for both installed and source-tree runs. The
+    fallback only matters when running from a raw checkout that was never
+    installed; there we read the version straight out of `pyproject.toml`.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("holdspeak")
+        except PackageNotFoundError:
+            pass
+    except Exception:
+        pass
+
+    try:
+        import re
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+        text = pyproject.read_text(encoding="utf-8")
+        match = re.search(r'(?m)^\s*version\s*=\s*"([^"]+)"', text)
+        if match:
+            return match.group(1)
+    except Exception:
+        pass
+
+    return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()

holdspeak/activity_candidates.py

@@ -0,0 +1,120 @@
+"""Local meeting-candidate extraction from activity records."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Iterable, Optional
+from urllib.parse import unquote
+
+from .db import ActivityRecord
+
+CALENDAR_CONNECTOR_ID = "calendar_activity"
+
+CALENDAR_DOMAINS = frozenset(
+    {
+        "calendar.google.com",
+        "meet.google.com",
+        "outlook.live.com",
+        "outlook.office.com",
+        "outlook.office365.com",
+        "teams.microsoft.com",
+    }
+)
+
+DATE_TIME_RE = re.compile(
+    r"\b(?P<date>\d{4}-\d{2}-\d{2})[T ]+"
+    r"(?P<start>\d{1,2}:\d{2})"
+    r"(?:\s*(?:-|to)\s*(?P<end>\d{1,2}:\d{2}))?\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class ActivityMeetingCandidatePreview:
+    """Preview of a meeting candidate derived from local activity only."""
+
+    title: str
+    starts_at: Optional[datetime]
+    ends_at: Optional[datetime]
+    meeting_url: str
+    source_activity_record_id: int
+    source_connector_id: str
+    confidence: float
+
+
+def preview_calendar_meeting_candidates(
+    records: Iterable[ActivityRecord],
+    *,
+    source_connector_id: str = CALENDAR_CONNECTOR_ID,
+    limit: int = 50,
+) -> list[ActivityMeetingCandidatePreview]:
+    """Derive meeting-candidate previews from existing local activity records."""
+    previews: list[ActivityMeetingCandidatePreview] = []
+    for record in records:
+        if not _is_calendar_record(record):
+            continue
+        title = _candidate_title(record)
+        starts_at, ends_at = _candidate_time_hints(record)
+        previews.append(
+            ActivityMeetingCandidatePreview(
+                title=title,
+                starts_at=starts_at,
+                ends_at=ends_at,
+                meeting_url=record.url,
+                source_activity_record_id=record.id,
+                source_connector_id=source_connector_id,
+                confidence=_candidate_confidence(record),
+            )
+        )
+        if len(previews) >= max(1, min(int(limit), 500)):
+            break
+    return previews
+
+
+def _is_calendar_record(record: ActivityRecord) -> bool:
+    domain = str(record.domain or "").strip().lower()
+    if domain in CALENDAR_DOMAINS:
+        return True
+    return any(domain.endswith(f".{candidate}") for candidate in CALENDAR_DOMAINS)
+
+
+def _candidate_title(record: ActivityRecord) -> str:
+    title = str(record.title or "").strip()
+    if title:
+        return title
+    if "teams.microsoft.com" in record.domain:
+        return "Microsoft Teams meeting"
+    if "meet.google.com" in record.domain:
+        return "Google Meet meeting"
+    if "outlook" in record.domain:
+        return "Outlook calendar event"
+    return "Calendar event"
+
+
+def _candidate_confidence(record: ActivityRecord) -> float:
+    title = str(record.title or "").lower()
+    if "meeting" in title or "calendar" in title:
+        return 0.75
+    if "teams.microsoft.com" in record.domain or "meet.google.com" in record.domain:
+        return 0.7
+    return 0.55
+
+
+def _candidate_time_hints(record: ActivityRecord) -> tuple[Optional[datetime], Optional[datetime]]:
+    text = f"{record.title or ''} {unquote(record.url or '')}"
+    match = DATE_TIME_RE.search(text)
+    if match is None:
+        return None, None
+    try:
+        starts_at = datetime.fromisoformat(f"{match.group('date')}T{match.group('start')}:00")
+        end_text = match.group("end")
+        if not end_text:
+            return starts_at, None
+        ends_at = datetime.fromisoformat(f"{match.group('date')}T{end_text}:00")
+        if ends_at < starts_at:
+            ends_at += timedelta(days=1)
+        return starts_at, ends_at
+    except ValueError:
+        return None, None

holdspeak/activity_connector_preview.py

@@ -0,0 +1,242 @@
+"""Shared dry-run harness for activity-enrichment connectors.
+
+HS-9-13. Each known connector (gh, jira, calendar_activity) describes
+what it *would* do via this harness without writing to the database.
+The result shape is the same for every connector so the browser can
+render a single dry-run preview surface.
+
+Mutation-free guarantee:
+
+  - The harness only reads from the database (`list_activity_records`).
+  - It calls each connector's preview helper, which itself does not
+    mutate state (`preview_github_cli_enrichment`, `preview_jira_cli_enrichment`,
+    `preview_calendar_meeting_candidates`).
+  - It does not call any *_run_* helper.
+
+Tests in `tests/integration/test_web_activity_api.py` assert that
+the row counts of `activity_annotations` and
+`activity_meeting_candidates` are unchanged after a dry-run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+from .activity_candidates import (
+    CALENDAR_CONNECTOR_ID,
+    preview_calendar_meeting_candidates,
+)
+from .activity_connectors import KNOWN_CONNECTORS, get_descriptor
+from .activity_github import (
+    CONNECTOR_ID as GH_CONNECTOR_ID,
+    SUPPORTED_ENTITY_TYPES as GH_SUPPORTED_ENTITY_TYPES,
+    preview_github_cli_enrichment,
+)
+from .activity_jira import (
+    CONNECTOR_ID as JIRA_CONNECTOR_ID,
+    SUPPORTED_ENTITY_TYPES as JIRA_SUPPORTED_ENTITY_TYPES,
+    preview_jira_cli_enrichment,
+)
+from .db import Database
+
+DEFAULT_LIMIT = 25
+MAX_LIMIT = 100
+
+# A safety cap on the per-section length of the dry-run payload so a
+# pathological local dataset cannot blow up the API response. Each
+# section (commands / proposed_annotations / proposed_candidates) is
+# truncated to this length and the result is flagged `truncated=True`.
+PAYLOAD_SECTION_CAP = 100
+
+
+@dataclass(frozen=True)
+class ConnectorDryRunResult:
+    """Uniform dry-run preview produced by `dry_run()`.
+
+    Every connector returns this shape. The browser renders the same
+    surface (commands → CommandPreview, proposed_* → list of cards,
+    warnings + permission_notes → inline messages) regardless of the
+    underlying connector kind.
+    """
+
+    connector_id: str
+    kind: str
+    capabilities: tuple[str, ...]
+    enabled: bool
+    cli_required: Optional[str]
+    cli_available: Optional[bool]
+    commands: tuple[Mapping[str, Any], ...] = field(default_factory=tuple)
+    proposed_annotations: tuple[Mapping[str, Any], ...] = field(default_factory=tuple)
+    proposed_candidates: tuple[Mapping[str, Any], ...] = field(default_factory=tuple)
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+    permission_notes: tuple[str, ...] = field(default_factory=tuple)
+    truncated: bool = False
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "connector_id": self.connector_id,
+            "kind": self.kind,
+            "capabilities": list(self.capabilities),
+            "enabled": self.enabled,
+            "cli_required": self.cli_required,
+            "cli_available": self.cli_available,
+            "commands": list(self.commands),
+            "proposed_annotations": list(self.proposed_annotations),
+            "proposed_candidates": list(self.proposed_candidates),
+            "warnings": list(self.warnings),
+            "permission_notes": list(self.permission_notes),
+            "truncated": self.truncated,
+        }
+
+
+class UnknownConnectorError(ValueError):
+    """Raised when `dry_run()` is given a connector id that isn't registered."""
+
+
+def dry_run(
+    db: Database,
+    connector_id: str,
+    *,
+    limit: int = DEFAULT_LIMIT,
+) -> ConnectorDryRunResult:
+    """Build a uniform mutation-free preview for one connector.
+
+    Returns a `ConnectorDryRunResult`. The caller is responsible for
+    serializing it via `to_payload()`. The harness does not raise on
+    a disabled connector or a missing CLI — those land in
+    `permission_notes` so the browser can render the would-do plan
+    alongside the reason it can't currently run.
+    """
+    descriptor = get_descriptor(connector_id)
+    if descriptor is None:
+        raise UnknownConnectorError(connector_id)
+
+    capped_limit = max(1, min(int(limit), MAX_LIMIT))
+    state = db.activity.get_activity_enrichment_connector(descriptor.id)
+    enabled = bool(state.enabled) if state is not None else False
+
+    cli_required = descriptor.requires_cli
+    cli_status = descriptor.cli_status() if cli_required else None
+    cli_available = bool(cli_status.get("available")) if cli_status else None
+
+    permission_notes: list[str] = []
+    if not enabled:
+        permission_notes.append(
+            f"{descriptor.label} is currently disabled. Dry-run shows what "
+            "the connector would do if you enabled it; nothing runs."
+        )
+    if cli_required and cli_available is False:
+        permission_notes.append(
+            f"`{cli_required}` CLI was not found on PATH. Install and "
+            "authenticate it before enabling this connector."
+        )
+
+    warnings: list[str] = []
+    commands: list[Mapping[str, Any]] = []
+    proposed_annotations: list[Mapping[str, Any]] = []
+    proposed_candidates: list[Mapping[str, Any]] = []
+
+    if descriptor.id == GH_CONNECTOR_ID:
+        records = []
+        for entity_type in GH_SUPPORTED_ENTITY_TYPES:
+            records.extend(
+                db.activity.list_activity_records(entity_type=entity_type, limit=capped_limit)
+            )
+        records = records[:capped_limit]
+        if not records:
+            warnings.append(
+                "No GitHub PR or issue activity has been imported yet. "
+                "Visit a PR or issue page in your browser, then refresh "
+                "the activity ledger."
+            )
+        preview = preview_github_cli_enrichment(records, limit=capped_limit)
+        commands = list(preview.get("commands", []))
+        for command in commands:
+            proposed_annotations.append(
+                {
+                    "annotation_type": command.get("annotation_type"),
+                    "activity_record_id": command.get("activity_record_id"),
+                    "entity_id": command.get("entity_id"),
+                    "title": f"Local {command.get('annotation_type')} annotation",
+                    "from_command": list(command.get("command", [])),
+                }
+            )
+
+    elif descriptor.id == JIRA_CONNECTOR_ID:
+        records = []
+        for entity_type in JIRA_SUPPORTED_ENTITY_TYPES:
+            records.extend(
+                db.activity.list_activity_records(entity_type=entity_type, limit=capped_limit)
+            )
+        records = records[:capped_limit]
+        if not records:
+            warnings.append(
+                "No Jira ticket activity has been imported yet. Visit "
+                "an Atlassian ticket in your browser, then refresh the "
+                "activity ledger."
+            )
+        preview = preview_jira_cli_enrichment(records, limit=capped_limit)
+        commands = list(preview.get("commands", []))
+        for command in commands:
+            proposed_annotations.append(
+                {
+                    "annotation_type": command.get("annotation_type"),
+                    "activity_record_id": command.get("activity_record_id"),
+                    "entity_id": command.get("entity_id"),
+                    "title": f"Local {command.get('annotation_type')} annotation",
+                    "from_command": list(command.get("command", [])),
+                }
+            )
+
+    elif descriptor.id == CALENDAR_CONNECTOR_ID:
+        records = db.activity.list_activity_records(limit=max(capped_limit * 4, 50))
+        previews = preview_calendar_meeting_candidates(records, limit=capped_limit)
+        if not previews:
+            warnings.append(
+                "No calendar / video-call activity has been imported "
+                "yet. Visit a Google Calendar event, Outlook event, or "
+                "Meet/Teams link, then refresh the activity ledger."
+            )
+        for preview in previews:
+            proposed_candidates.append(
+                {
+                    "title": preview.title,
+                    "starts_at": preview.starts_at.isoformat() if preview.starts_at else None,
+                    "ends_at": preview.ends_at.isoformat() if preview.ends_at else None,
+                    "meeting_url": preview.meeting_url,
+                    "source_activity_record_id": preview.source_activity_record_id,
+                    "source_connector_id": preview.source_connector_id,
+                    "confidence": preview.confidence,
+                }
+            )
+
+    truncated = False
+    if len(commands) > PAYLOAD_SECTION_CAP:
+        commands = commands[:PAYLOAD_SECTION_CAP]
+        truncated = True
+    if len(proposed_annotations) > PAYLOAD_SECTION_CAP:
+        proposed_annotations = proposed_annotations[:PAYLOAD_SECTION_CAP]
+        truncated = True
+    if len(proposed_candidates) > PAYLOAD_SECTION_CAP:
+        proposed_candidates = proposed_candidates[:PAYLOAD_SECTION_CAP]
+        truncated = True
+
+    return ConnectorDryRunResult(
+        connector_id=descriptor.id,
+        kind=descriptor.kind,
+        capabilities=descriptor.capabilities,
+        enabled=enabled,
+        cli_required=cli_required,
+        cli_available=cli_available,
+        commands=tuple(commands),
+        proposed_annotations=tuple(proposed_annotations),
+        proposed_candidates=tuple(proposed_candidates),
+        warnings=tuple(warnings),
+        permission_notes=tuple(permission_notes),
+        truncated=truncated,
+    )
+
+
+def known_connector_ids() -> tuple[str, ...]:
+    return tuple(c.id for c in KNOWN_CONNECTORS)

holdspeak/activity_connectors.py

@@ -0,0 +1,140 @@
+"""Pack-derived registry of activity connectors known to the runtime.
+
+HS-13-01 + HS-13-04. The runtime registry now derives from
+both first-party packs (`connector_packs.ALL_PACKS`) and any
+user packs discovered under `~/.holdspeak/connector_packs/`
+via `connector_pack_loader.build_registry`. The descriptor
+surface is unchanged for downstream consumers; only the source
+field on `ConnectorDescriptor` and the new
+`reload_registry()`/`discovery_errors()` helpers are new.
+
+`ConnectorDescriptor` carries:
+
+  - `id`, `label`, `kind`, `capabilities`, `requires_cli`,
+    `description` — sourced from the manifest.
+  - `source` — `"first-party"` or `"user"` so the API + doctor
+    can label each connector by provenance.
+  - `manifest` — the underlying `ConnectorManifest`.
+  - `cli_status()` — dispatches by id (gh / jira only).
+
+The descriptor's `capabilities` is the manifest's
+`capabilities` filtered to row-producing capabilities so the
+manifest's `commands` / pure-preview capabilities don't leak
+into API consumers expecting a row-shape.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .activity_github import CONNECTOR_ID as GH_CONNECTOR_ID, github_cli_status
+from .activity_jira import CONNECTOR_ID as JIRA_CONNECTOR_ID, jira_cli_status
+from .connector_pack_loader import (
+    DiscoveryResult,
+    RegisteredPack,
+    build_registry,
+)
+from .connector_sdk import ConnectorManifest
+
+_ROW_CAPABILITIES: frozenset[str] = frozenset({"records", "annotations", "candidates"})
+
+ENRICHMENT_KINDS: frozenset[str] = frozenset(
+    {"cli_enrichment", "candidate_inference"}
+)
+
+
+@dataclass(frozen=True)
+class ConnectorDescriptor:
+    """Runtime view of one pack-registered connector."""
+
+    id: str
+    label: str
+    kind: str
+    capabilities: tuple[str, ...]
+    requires_cli: Optional[str]
+    description: str
+    source: str
+    manifest: ConnectorManifest
+
+    def cli_status(self) -> Optional[dict]:
+        if self.id == GH_CONNECTOR_ID:
+            return github_cli_status()
+        if self.id == JIRA_CONNECTOR_ID:
+            return jira_cli_status()
+        return None
+
+
+def _descriptor_from_pack(pack: RegisteredPack) -> ConnectorDescriptor:
+    manifest = pack.manifest
+    return ConnectorDescriptor(
+        id=manifest.id,
+        label=manifest.label,
+        kind=manifest.kind,
+        capabilities=tuple(c for c in manifest.capabilities if c in _ROW_CAPABILITIES),
+        requires_cli=manifest.requires_cli,
+        description=manifest.description,
+        source=pack.source,
+        manifest=manifest,
+    )
+
+
+# ───────────────────── Module-level registry state ────────────────────
+#
+# Populated at import time and refreshable via `reload_registry`.
+# The web API + the dry-run harness + the fixture runner all
+# read these globals; tests that exercise user-pack discovery
+# call `reload_registry(user_packs_dir=tmp_path)` to swap them.
+
+_DISCOVERY: DiscoveryResult = DiscoveryResult()
+KNOWN_CONNECTORS: tuple[ConnectorDescriptor, ...] = ()
+KNOWN_CONNECTOR_IDS: frozenset[str] = frozenset()
+
+
+def _apply_discovery(result: DiscoveryResult) -> None:
+    global _DISCOVERY, KNOWN_CONNECTORS, KNOWN_CONNECTOR_IDS
+    _DISCOVERY = result
+    KNOWN_CONNECTORS = tuple(_descriptor_from_pack(p) for p in result.packs)
+    KNOWN_CONNECTOR_IDS = frozenset(c.id for c in KNOWN_CONNECTORS)
+
+
+def reload_registry(
+    user_packs_dir: Optional[Path] = None,
+) -> DiscoveryResult:
+    """Recompute the registry. Returns the resulting
+    `DiscoveryResult` for callers that want to inspect errors.
+
+    Tests use this to swap in a tmp_path-scoped user-pack dir.
+    Production code calls it implicitly at module import; a
+    runtime restart re-discovers any new files dropped into
+    `~/.holdspeak/connector_packs/`.
+    """
+    result = build_registry(user_packs_dir=user_packs_dir)
+    _apply_discovery(result)
+    return result
+
+
+def discovery_errors() -> tuple:
+    """Return the discovery errors from the most recent registry
+    load. Doctor + the API surface these so a malformed user
+    pack is visible without grepping logs."""
+    return _DISCOVERY.errors
+
+
+def get_descriptor(connector_id: str) -> Optional[ConnectorDescriptor]:
+    for descriptor in KNOWN_CONNECTORS:
+        if descriptor.id == connector_id:
+            return descriptor
+    return None
+
+
+def enrichment_descriptors() -> tuple[ConnectorDescriptor, ...]:
+    """Subset of the registry that drives the activity-enrichment
+    surface. Records-ingesters (firefox_ext) live in the registry
+    but not on this surface."""
+    return tuple(c for c in KNOWN_CONNECTORS if c.kind in ENRICHMENT_KINDS)
+
+
+# Initial load at module-import time.
+reload_registry()

holdspeak/activity_context.py

@@ -0,0 +1,154 @@
+"""Shared activity context bundles for HoldSpeak plugins."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from threading import Lock
+from typing import Any, Optional
+
+from .activity_history import import_browser_history
+from .db import ActivityRecord, Database, get_database
+from .logging_config import get_logger
+
+log = get_logger("activity_context")
+
+
+@dataclass(frozen=True)
+class ActivityContextBundle:
+    """Serializable local activity context for plugin consumers."""
+
+    records: list[dict[str, Any]]
+    entity_counts: dict[str, int]
+    domain_counts: dict[str, int]
+    source_counts: dict[str, int]
+    generated_at: str
+    project_id: Optional[str] = None
+    refreshed: bool = False
+    refresh_errors: list[str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "records": list(self.records),
+            "entity_counts": dict(self.entity_counts),
+            "domain_counts": dict(self.domain_counts),
+            "source_counts": dict(self.source_counts),
+            "generated_at": self.generated_at,
+            "project_id": self.project_id,
+            "refreshed": self.refreshed,
+            "refresh_errors": list(self.refresh_errors or []),
+        }
+
+
+class ActivityContextProvider:
+    """Callable context provider that injects local activity into plugins."""
+
+    def __init__(
+        self,
+        *,
+        db: Database | None = None,
+        limit: int = 20,
+        refresh: bool = False,
+        refresh_once: bool = True,
+        importer: Callable[..., Any] = import_browser_history,
+    ) -> None:
+        self._db = db
+        self._limit = max(1, min(int(limit), 200))
+        self._refresh = bool(refresh)
+        self._refresh_once = bool(refresh_once)
+        self._importer = importer
+        self._lock = Lock()
+        self._refreshed = False
+
+    def __call__(self, context: dict[str, Any]) -> dict[str, Any]:
+        project_id = _project_id_from_context(context)
+        bundle = build_activity_context(
+            db=self._db,
+            project_id=project_id,
+            limit=self._limit,
+            refresh=self._should_refresh(),
+            importer=self._importer,
+        )
+        return {"activity": bundle.to_dict()}
+
+    def _should_refresh(self) -> bool:
+        if not self._refresh:
+            return False
+        with self._lock:
+            if self._refresh_once and self._refreshed:
+                return False
+            self._refreshed = True
+            return True
+
+
+def build_activity_context(
+    *,
+    db: Database | None = None,
+    project_id: Optional[str] = None,
+    limit: int = 20,
+    refresh: bool = False,
+    importer: Callable[..., Any] = import_browser_history,
+) -> ActivityContextBundle:
+    """Build a plugin-safe local activity context bundle."""
+    database = db or get_database()
+    refresh_errors: list[str] = []
+    did_refresh = False
+    if refresh:
+        try:
+            results = importer(db=database)
+            did_refresh = True
+            refresh_errors = [
+                str(result.error)
+                for result in results
+                if getattr(result, "error", None)
+            ]
+        except Exception as exc:
+            refresh_errors.append(f"{type(exc).__name__}: {exc}")
+            log.warning("Activity context refresh failed: %s", exc)
+
+    records = database.activity.list_activity_records(
+        project_id=project_id,
+        limit=max(1, min(int(limit), 200)),
+    )
+    serialized = [_serialize_activity_record(record) for record in records]
+    return ActivityContextBundle(
+        records=serialized,
+        entity_counts=dict(Counter(item["entity_type"] for item in serialized if item["entity_type"])),
+        domain_counts=dict(Counter(item["domain"] for item in serialized if item["domain"])),
+        source_counts=dict(Counter(item["source_browser"] for item in serialized if item["source_browser"])),
+        generated_at=datetime.now().isoformat(),
+        project_id=project_id,
+        refreshed=did_refresh,
+        refresh_errors=refresh_errors,
+    )
+
+
+def _serialize_activity_record(record: ActivityRecord) -> dict[str, Any]:
+    return {
+        "id": record.id,
+        "source_browser": record.source_browser,
+        "source_profile": record.source_profile,
+        "url": record.url,
+        "title": record.title,
+        "domain": record.domain,
+        "visit_count": record.visit_count,
+        "first_seen_at": record.first_seen_at.isoformat() if record.first_seen_at else None,
+        "last_seen_at": record.last_seen_at.isoformat() if record.last_seen_at else None,
+        "entity_type": record.entity_type,
+        "entity_id": record.entity_id,
+        "project_id": record.project_id,
+    }
+
+
+def _project_id_from_context(context: dict[str, Any]) -> Optional[str]:
+    raw_project_id = context.get("project_id")
+    if raw_project_id not in (None, ""):
+        return str(raw_project_id)
+    project = context.get("project")
+    if isinstance(project, dict):
+        raw_project_id = project.get("id") or project.get("project_id")
+        if raw_project_id not in (None, ""):
+            return str(raw_project_id)
+    return None