poliora 0.2.0__py3-none-any.whl

poliora/__init__.py

@@ -0,0 +1,7 @@
+"""Poliora - AI cost, carbon, and fine-tuning efficiency toolkit."""
+
+from poliora.cost import log_openai_response, log_usage, track_anthropic_client, track_openai_client
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "log_openai_response", "log_usage", "track_anthropic_client", "track_openai_client"]

poliora/app_launcher.py

@@ -0,0 +1,83 @@
+"""Standalone Desktop App launcher for Poliora."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import sys
+import webbrowser
+from pathlib import Path
+from threading import Timer
+
+from poliora.cost import init_workspace, load_workspace
+from poliora.web import run_dashboard
+
+
+def _available_port(preferred_port: int) -> int:
+    """Return the preferred loopback port, or the next available one."""
+    for port in range(preferred_port, preferred_port + 20):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if probe.connect_ex(("127.0.0.1", port)) != 0:
+                return port
+    raise RuntimeError("No local dashboard port was available in the configured range.")
+
+
+def _desktop_workspace_root() -> Path:
+    """Choose the normal per-user application-data location for the desktop app."""
+    if sys.platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")) / "Poliora" / "workspace"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Poliora" / "workspace"
+    data_home = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    return data_home / "poliora" / "workspace"
+
+
+def main() -> None:
+    """Launch Poliora standalone GUI application."""
+    parser = argparse.ArgumentParser(description="Launch the Poliora local dashboard.")
+    parser.add_argument("--version", action="store_true", help="Show the standalone app version and exit.")
+    parser.add_argument("--port", type=int, default=8787, help="Preferred local dashboard port.")
+    parser.add_argument("--no-open", action="store_true", help="Do not open a browser window.")
+    arguments = parser.parse_args()
+    if arguments.version:
+        from poliora import __version__
+
+        print(f"poliora {__version__}")
+        return
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+    print("=" * 60)
+    print(" [Poliora] Starting Desktop AI Cost Optimizer...")
+    print("=" * 60)
+
+    workspace_root = _desktop_workspace_root()
+    workspace = load_workspace(workspace_root)
+    if not workspace.config_path.exists():
+        init_workspace(workspace_root, project="Desktop", monthly_budget_usd=1000.0)
+
+    port = _available_port(arguments.port)
+    url = f"http://127.0.0.1:{port}"
+    print(f"\n[+] Poliora engine running at {url}")
+    print("[+] Opening Desktop Application interface...")
+
+    # Open browser window automatically after 0.5s
+    if not arguments.no_open:
+        Timer(0.5, webbrowser.open_new_tab, args=(url,)).start()
+
+    # Serve local dashboard server
+    try:
+        run_dashboard(workspace_root, host="127.0.0.1", port=port)
+    except KeyboardInterrupt:
+        print("\nPoliora closed. Goodbye!")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

poliora/config.py

@@ -0,0 +1,103 @@
+"""Poliora configuration — Pydantic settings for every tunable knob."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings
+
+
+class PolioraConfig(BaseSettings):
+    """Central configuration for a Poliora training run.
+
+    Values can be set via constructor kwargs, environment variables prefixed
+    with ``POLIORA_`` (e.g. ``POLIORA_MODEL_NAME``), or a ``.env`` file.
+    """
+
+    # ── Model & Data ─────────────────────────────────────────────────────
+    model_name: str = Field(
+        default="microsoft/phi-3-mini-4k-instruct",
+        description="Hugging Face model identifier or local path.",
+    )
+    dataset_path: Path = Field(
+        default=Path("data.csv"),
+        description="Path to a CSV dataset with at least a 'text' column.",
+    )
+    output_dir: Path = Field(
+        default=Path("tuned_model"),
+        description="Directory where the trained model will be saved.",
+    )
+    text_column: str = Field(
+        default="text",
+        description="Name of the text column in the CSV dataset.",
+    )
+    label_column: Optional[str] = Field(
+        default=None,
+        description="Optional name of the label column (for evaluation).",
+    )
+
+    # ── Training hyper-parameters ────────────────────────────────────────
+    epochs: int = Field(default=3, ge=1, description="Number of training epochs.")
+    batch_size: int = Field(default=4, ge=1, description="Per-device batch size.")
+    learning_rate: float = Field(default=2e-4, gt=0, description="Learning rate.")
+    max_seq_length: int = Field(default=512, ge=32, description="Maximum token sequence length.")
+    eval_split: float = Field(
+        default=0.1, ge=0.0, le=0.5,
+        description="Fraction of data to hold out for evaluation (0 = skip eval).",
+    )
+
+    # ── Optimisations ────────────────────────────────────────────────────
+    use_lora: bool = Field(default=True, description="Apply LoRA adapters for parameter-efficient training.")
+    lora_rank: int = Field(default=8, ge=1, description="LoRA rank (r).")
+    lora_alpha: int = Field(default=16, ge=1, description="LoRA alpha scaling factor.")
+    lora_dropout: float = Field(default=0.05, ge=0.0, le=1.0, description="LoRA dropout probability.")
+
+    use_quantization: bool = Field(default=True, description="Load model in quantised mode (bitsandbytes).")
+    quant_bits: Literal[4, 8] = Field(default=4, description="Quantisation bitwidth — 4 or 8.")
+    low_memory: bool = Field(default=False, description="Enable aggressive memory-saving tweaks.")
+
+    # ── Carbon tracking ──────────────────────────────────────────────────
+    track_carbon: bool = Field(default=True, description="Track energy & CO2 with CodeCarbon.")
+    country_iso_code: str = Field(default="USA", description="ISO 3166-1 alpha-3 country code for carbon intensity.")
+
+    # ── API keys (optional) ──────────────────────────────────────────────
+    electricity_maps_key: Optional[str] = Field(
+        default=None,
+        description="Electricity Maps API key for real-time grid carbon intensity.",
+    )
+    electricity_zone: str = Field(
+        default="US",
+        description="Electricity Maps zone code (e.g. 'US-CAL-CISO', 'DE', 'FR').",
+    )
+    grok_api_key: Optional[str] = Field(
+        default=None,
+        description="Grok / xAI API key for LLM-powered eco-tips.",
+    )
+
+    # ── Benchmark ────────────────────────────────────────────────────────
+    benchmark_output_dir: Path = Field(
+        default=Path("benchmark_output"),
+        description="Directory for benchmark reports.",
+    )
+    benchmark_export_json: Optional[Path] = Field(
+        default=None,
+        description="Path to write the benchmark JSON report.",
+    )
+    benchmark_export_csv: Optional[Path] = Field(
+        default=None,
+        description="Path to write the benchmark CSV report.",
+    )
+
+    model_config = {"env_prefix": "POLIORA_", "env_file": ".env", "extra": "ignore"}
+
+    # ── Validators ───────────────────────────────────────────────────────
+
+    @field_validator("dataset_path")
+    @classmethod
+    def _dataset_exists(cls, v: Path) -> Path:
+        """Warn early if the dataset path doesn't exist."""
+        if not v.exists():
+            raise FileNotFoundError(f"Dataset not found: {v}")
+        return v

poliora/cost/__init__.py

@@ -0,0 +1,134 @@
+"""AI spend tracking primitives for Poliora."""
+
+from poliora.cost.antigravity import (
+    AntigravityPluginInstall,
+    install_antigravity_plugin,
+    record_antigravity_hook_event,
+)
+from poliora.cost.budget import BudgetCheck, check_budget
+from poliora.cost.capture import (
+    CapturedCall,
+    track_anthropic_call,
+    track_anthropic_client,
+    track_gemini_call,
+    track_gemini_client,
+    track_openai_call,
+    track_openai_client,
+    track_openai_compatible_call,
+    track_openai_compatible_client,
+)
+from poliora.cost.catalog import CatalogModel, ModelCatalog
+from poliora.cost.codex_exec import CodexCli, find_codex_cli, record_codex_exec_event
+from poliora.cost.companion import ConnectorConnection, ConnectorDefinition, ConnectorStore, connector_catalog
+from poliora.cost.dashboard import ReportBranding, render_html_report, write_html_report
+from poliora.cost.decisions import (
+    DECISION_STATUSES,
+    QUALITY_STATUSES,
+    DecisionStore,
+    SavingsDecision,
+    SavingsLedgerSummary,
+    summarize_decisions,
+)
+from poliora.cost.detection import DetectedTool, detect_local_tools
+from poliora.cost.importer import (
+    CsvImportPreview,
+    CsvImportResult,
+    CsvRowIssue,
+    import_usage_csv,
+    import_usage_csv_text,
+    preview_usage_csv,
+    preview_usage_csv_text,
+)
+from poliora.cost.local_usage import (
+    DetectedPlan,
+    LocalUsageScan,
+    read_claude_code_usage,
+    read_codex_usage,
+    scan_local_usage,
+)
+from poliora.cost.pricing import ModelPricing, PricingRegistry, estimate_cost_usd
+from poliora.cost.recommendations import Recommendation, generate_recommendations
+from poliora.cost.reports import DailySpendRow, SpendAnomaly, UsageReport, build_usage_report
+from poliora.cost.scanner import SystemScanReport, ToolScanResult, scan_system_ai_environment
+from poliora.cost.scenarios import SavedScenario, ScenarioStore
+from poliora.cost.sdk import log_anthropic_response, log_gemini_response, log_openai_response, log_usage
+from poliora.cost.simulation import ModelSwitchSimulation, simulate_model_switch
+from poliora.cost.sync import ModelSyncResult, sync_provider_models
+from poliora.cost.usage import JsonlUsageStore, UsageEvent
+from poliora.cost.workspace import PolioraWorkspace, init_workspace, load_workspace
+
+__all__ = [
+    "CapturedCall",
+    "AntigravityPluginInstall",
+    "CatalogModel",
+    "CodexCli",
+    "ConnectorConnection",
+    "ConnectorDefinition",
+    "ConnectorStore",
+    "BudgetCheck",
+    "CsvImportResult",
+    "CsvImportPreview",
+    "CsvRowIssue",
+    "DECISION_STATUSES",
+    "DailySpendRow",
+    "DecisionStore",
+    "DetectedTool",
+    "PolioraWorkspace",
+    "JsonlUsageStore",
+    "ModelPricing",
+    "ModelCatalog",
+    "ModelSwitchSimulation",
+    "ModelSyncResult",
+    "PricingRegistry",
+    "Recommendation",
+    "ReportBranding",
+    "QUALITY_STATUSES",
+    "SavedScenario",
+    "SavingsDecision",
+    "SavingsLedgerSummary",
+    "ScenarioStore",
+    "SpendAnomaly",
+    "SystemScanReport",
+    "ToolScanResult",
+    "UsageEvent",
+    "UsageReport",
+    "build_usage_report",
+    "check_budget",
+    "connector_catalog",
+    "detect_local_tools",
+    "DetectedPlan",
+    "LocalUsageScan",
+    "read_claude_code_usage",
+    "read_codex_usage",
+    "scan_local_usage",
+    "estimate_cost_usd",
+    "find_codex_cli",
+    "generate_recommendations",
+    "init_workspace",
+    "install_antigravity_plugin",
+    "import_usage_csv",
+    "import_usage_csv_text",
+    "load_workspace",
+    "log_anthropic_response",
+    "log_gemini_response",
+    "log_openai_response",
+    "log_usage",
+    "render_html_report",
+    "preview_usage_csv",
+    "preview_usage_csv_text",
+    "record_codex_exec_event",
+    "record_antigravity_hook_event",
+    "scan_system_ai_environment",
+    "simulate_model_switch",
+    "sync_provider_models",
+    "summarize_decisions",
+    "track_anthropic_call",
+    "track_anthropic_client",
+    "track_gemini_call",
+    "track_gemini_client",
+    "track_openai_call",
+    "track_openai_client",
+    "track_openai_compatible_call",
+    "track_openai_compatible_client",
+    "write_html_report",
+]

poliora/cost/antigravity.py

@@ -0,0 +1,182 @@
+"""Supported Antigravity activity capture and plugin installation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shlex
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from poliora.cost.usage import JsonlUsageStore, UsageEvent
+from poliora.cost.workspace import load_workspace
+
+
+@dataclass(frozen=True)
+class AntigravityPluginInstall:
+    """Location and scope of an installed Antigravity plugin."""
+
+    path: Path
+    scope: str
+
+
+def record_antigravity_hook_event(
+    payload: dict[str, Any],
+    *,
+    event_name: str,
+    root: str | Path | None = None,
+) -> UsageEvent | None:
+    """Record metadata exposed by an official Antigravity lifecycle hook.
+
+    Antigravity hooks do not currently expose model IDs or token totals. The
+    resulting event is therefore activity-only and is excluded from spend.
+    """
+    if event_name != "pre-invocation":
+        return None
+
+    workspace_root = Path(root).resolve() if root is not None else _workspace_root(payload)
+    workspace = load_workspace(workspace_root)
+    invocation_num = _non_negative_int(payload.get("invocationNum"), "invocationNum")
+    conversation_id = str(payload.get("conversationId") or "")
+    trace_id = _anonymous_trace_id(conversation_id) if conversation_id else None
+
+    event = UsageEvent(
+        provider="google",
+        model="antigravity-managed",
+        input_tokens=0,
+        output_tokens=0,
+        cost_usd=0.0,
+        operation="antigravity-agent",
+        project=workspace.project,
+        trace_id=trace_id,
+        metadata={
+            "source": "antigravity-pre-invocation-hook",
+            "billing_basis": "antigravity-subscription-activity",
+            "invocation_num": invocation_num,
+            "content_collected": False,
+            "token_usage_available": False,
+        },
+    )
+    JsonlUsageStore(workspace.usage_path).append(event)
+    return event
+
+
+def install_antigravity_plugin(
+    root: str | Path = ".",
+    *,
+    scope: str = "workspace",
+    force: bool = False,
+) -> AntigravityPluginInstall:
+    """Install Poliora into one of Antigravity's documented plugin locations."""
+    plugin_path = _plugin_path(Path(root).resolve(), scope)
+    manifest_path = plugin_path / "plugin.json"
+    if manifest_path.exists() and not force:
+        try:
+            existing = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise ValueError(f"Refusing to replace an unreadable plugin at {plugin_path}.") from error
+        if existing.get("name") != "poliora":
+            raise ValueError(f"A different plugin already exists at {plugin_path}. Use --force to replace it.")
+
+    files = {
+        "plugin.json": json.dumps({"name": "poliora"}, indent=2) + "\n",
+        "hooks.json": json.dumps(_hook_config(), indent=2) + "\n",
+        "skills/poliora-cost/SKILL.md": _skill_markdown(),
+        "rules/poliora-privacy.md": _privacy_rule_markdown(),
+    }
+    for relative_path, content in files.items():
+        destination = plugin_path / relative_path
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding="utf-8")
+    return AntigravityPluginInstall(path=plugin_path, scope=scope)
+
+
+def _workspace_root(payload: dict[str, Any]) -> Path:
+    paths = payload.get("workspacePaths")
+    if isinstance(paths, list):
+        candidates = [Path(item).resolve() for item in paths if isinstance(item, str) and item.strip()]
+        for candidate in candidates:
+            if (candidate / ".poliora" / "config.json").exists():
+                return candidate
+        if candidates:
+            return candidates[0]
+    return Path.cwd().resolve()
+
+
+def _plugin_path(root: Path, scope: str) -> Path:
+    if scope == "workspace":
+        return root / ".agents" / "plugins" / "poliora"
+    if scope == "editor-global":
+        return Path.home() / ".gemini" / "config" / "plugins" / "poliora"
+    if scope == "cli-global":
+        return Path.home() / ".gemini" / "antigravity-cli" / "plugins" / "poliora"
+    raise ValueError("scope must be workspace, editor-global, or cli-global")
+
+
+def _hook_config() -> dict[str, object]:
+    return {
+        "poliora-activity": {
+            "PreInvocation": [
+                {
+                    "type": "command",
+                    "command": _hook_command(),
+                    "timeout": 10,
+                }
+            ]
+        }
+    }
+
+
+def _hook_command() -> str:
+    arguments = [sys.executable, "-m", "poliora.main", "antigravity-hook", "--event", "pre-invocation"]
+    if os.name == "nt":
+        return subprocess.list2cmdline(arguments)
+    return shlex.join(arguments)
+
+
+def _skill_markdown() -> str:
+    return """---
+name: poliora-cost
+description: Inspect and improve local AI usage with Poliora.
+---
+
+# Poliora Cost Operations
+
+Use Poliora when the user asks about AI spend, model usage, budgets, or routing savings.
+
+- Run `poliora report` for the local usage summary.
+- Run `poliora recommend` for prioritized savings opportunities.
+- Run `poliora dashboard` only when the user asks to open the local dashboard.
+- For Gemini API code, wrap `google.genai.Client` with `poliora.cost.track_gemini_client`.
+- Never infer token counts, model IDs, or dollar cost from Antigravity activity-only events.
+"""
+
+
+def _privacy_rule_markdown() -> str:
+    return """# Poliora Privacy
+
+Poliora may record lifecycle metadata and provider-reported usage totals. Do not send prompt text,
+responses, source files, commands, transcript contents, credentials, or file-change content to Poliora.
+Antigravity subscription activity must remain separate from measured or estimated API spend.
+"""
+
+
+def _anonymous_trace_id(conversation_id: str) -> str:
+    digest = hashlib.sha256(conversation_id.encode("utf-8")).hexdigest()
+    return f"antigravity-{digest[:16]}"
+
+
+def _non_negative_int(value: Any, field: str) -> int:
+    if isinstance(value, bool):
+        raise ValueError(f"Antigravity {field} must be a non-negative integer.")
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"Antigravity {field} must be a non-negative integer.") from error
+    if parsed < 0:
+        raise ValueError(f"Antigravity {field} must be a non-negative integer.")
+    return parsed

poliora/cost/budget.py

@@ -0,0 +1,52 @@
+"""Budget checks for local reports and CI gates."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from poliora.cost.reports import UsageReport
+
+
+@dataclass(frozen=True)
+class BudgetCheck:
+    """Result of comparing projected spend against a budget."""
+
+    passed: bool
+    projected_monthly_usd: float
+    limit_usd: float
+    used_pct: float
+    remaining_usd: float
+    message: str
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize budget check."""
+        return asdict(self)
+
+
+def check_budget(report: UsageReport, *, limit_usd: float, warn_at_pct: float = 80.0) -> BudgetCheck:
+    """Check whether projected monthly spend is within a budget."""
+    if limit_usd <= 0:
+        raise ValueError("Budget limit must be greater than zero.")
+    if warn_at_pct <= 0:
+        raise ValueError("warn_at_pct must be greater than zero.")
+
+    projected = report.projected_monthly_usd
+    used_pct = round(projected / limit_usd * 100, 2)
+    remaining = round(limit_usd - projected, 2)
+    passed = projected <= limit_usd
+
+    if not passed:
+        message = f"Projected AI spend is ${projected:,.2f}, above the ${limit_usd:,.2f} limit."
+    elif used_pct >= warn_at_pct:
+        message = f"Projected AI spend is at {used_pct:.1f}% of budget. Watch this closely."
+    else:
+        message = f"Projected AI spend is within budget with ${remaining:,.2f} remaining."
+
+    return BudgetCheck(
+        passed=passed,
+        projected_monthly_usd=projected,
+        limit_usd=limit_usd,
+        used_pct=used_pct,
+        remaining_usd=remaining,
+        message=message,
+    )