karani 0.3.0__py3-none-any.whl

karani/__init__.py

@@ -0,0 +1,8 @@
+"""karani — a semi-autonomous, self-hosted job-application pipeline.
+
+Hunts postings hourly, qualifies them against your resume, drafts full
+application packs, and delivers them for human review. It never submits.
+"""
+from __future__ import annotations
+
+__version__ = "0.3.0"

karani/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m karani` == the `karani` CLI."""
+from __future__ import annotations
+
+from karani.cli import main
+
+if __name__ == "__main__":
+    main()

karani/artifacts/__init__.py

@@ -0,0 +1,12 @@
+"""Per-job application artifacts in S3-compatible object storage.
+
+One prefix per job (resume, cover letter, pack, prep, follow-up), with
+presigned links surfaced on the Slack review card — click, tweak, submit.
+Optional and best-effort: unconfigured or unreachable MinIO degrades to
+files-on-disk, never fails a draft. See docs/adrs/0014.
+"""
+from __future__ import annotations
+
+from .store import ArtifactStore
+
+__all__ = ["ArtifactStore"]

karani/artifacts/store.py

@@ -0,0 +1,111 @@
+"""MinIO/S3 artifact store — guarded import, env-configured, best-effort.
+
+Defaults target karani's own compose MinIO (localhost:9010; the DataQRL
+stack owns 9000). Point MINIO_ENDPOINT at any S3-compatible service.
+"""
+from __future__ import annotations
+
+import asyncio
+import io
+import logging
+import os
+import re
+from datetime import timedelta
+
+log = logging.getLogger(__name__)
+
+DEFAULT_ENDPOINT = "localhost:9010"
+DEFAULT_BUCKET = "karani-applications"
+PRESIGN_DAYS = int(os.getenv("MINIO_PRESIGN_DAYS", "7"))
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", (text or "").lower()).strip("-") or "co"
+
+
+class ArtifactStore:
+    """Sync minio SDK wrapped for async use. Construct via `create()`."""
+
+    def __init__(self, client, bucket: str):
+        self._client = client
+        self._bucket = bucket
+
+    @staticmethod
+    def configured() -> bool:
+        return bool(os.getenv("MINIO_ACCESS_KEY")
+                    and os.getenv("MINIO_SECRET_KEY"))
+
+    @classmethod
+    async def create(cls) -> "ArtifactStore | None":
+        """Connect and ensure the bucket; None when unconfigured/unavailable."""
+        if not cls.configured():
+            return None
+        try:
+            from minio import Minio  # optional: uv sync --extra artifacts
+        except ImportError:
+            log.warning("minio SDK not installed; artifacts stay on disk "
+                        "(uv sync --extra artifacts)")
+            return None
+        try:
+            from karani.config import get_config
+            from karani.config.loader import resolve
+            acfg = get_config().artifacts
+            client = Minio(
+                resolve("MINIO_ENDPOINT", acfg.endpoint, DEFAULT_ENDPOINT),
+                access_key=os.getenv("MINIO_ACCESS_KEY"),
+                secret_key=os.getenv("MINIO_SECRET_KEY"),
+                secure=os.getenv("MINIO_SECURE", "false").lower() == "true",
+            )
+            bucket = resolve("MINIO_BUCKET", acfg.bucket, DEFAULT_BUCKET)
+
+            def _ensure():
+                if not client.bucket_exists(bucket):
+                    client.make_bucket(bucket)
+            await asyncio.to_thread(_ensure)
+            return cls(client, bucket)
+        except Exception as exc:
+            log.warning("artifact store unavailable (%s); files stay on "
+                        "disk", exc)
+            return None
+
+    @staticmethod
+    def key(job_row: dict, name: str) -> str:
+        jid = job_row.get("id", 0)
+        company = _slug(job_row.get("company_display")
+                        or job_row.get("company") or "")
+        return f"{jid:05d}-{company}/{name}"
+
+    async def put_text(self, key: str, content: str) -> str:
+        data = content.encode("utf-8")
+
+        def _put():
+            self._client.put_object(
+                self._bucket, key, io.BytesIO(data), len(data),
+                content_type="text/markdown; charset=utf-8",
+            )
+        await asyncio.to_thread(_put)
+        return key
+
+    async def presign(self, key: str) -> str:
+        def _sign():
+            return self._client.presigned_get_object(
+                self._bucket, key, expires=timedelta(days=PRESIGN_DAYS),
+            )
+        return await asyncio.to_thread(_sign)
+
+    async def store_pack(self, job_row: dict, files: dict[str, str]) -> dict:
+        """Upload {name: content} for one job; returns {name: {key, url}}.
+
+        Best-effort per file — one failed upload never sinks the pack.
+        """
+        out: dict[str, dict] = {}
+        for name, content in files.items():
+            if not content:
+                continue
+            try:
+                key = self.key(job_row, name)
+                await self.put_text(key, content)
+                out[name] = {"key": key, "url": await self.presign(key)}
+            except Exception as exc:
+                log.warning("artifact upload failed for %s: %s", name, exc)
+        return out

karani/autopilot/__init__.py

@@ -0,0 +1,12 @@
+"""Autopilot — the continuous hunt (ADR 0012).
+
+Drafts application packs for top-fit qualified roles without waiting for
+a verdict, and delivers them to Slack with review buttons. Guardrails:
+fit floor (AUTOPILOT_MIN_FIT), per-run draft cap (AUTOPILOT_MAX_DRAFTS),
+and the hard non-goal — karani never submits an application.
+"""
+from __future__ import annotations
+
+from .runner import run_autopilot
+
+__all__ = ["run_autopilot"]

karani/autopilot/runner.py

@@ -0,0 +1,108 @@
+"""Autopilot pass: candidates -> draft pack -> Slack review card.
+
+Runs inside the scheduled daily chain. Per-job failures are contained —
+one bad draft or Slack hiccup skips that job and continues; the next
+pass retries anything still eligible (drafted jobs move to `drafting`,
+so they leave the candidate pool).
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from karani.ingestion.storage import Storage
+from karani.notionsync import maybe_sync_job
+
+log = logging.getLogger(__name__)
+
+def _caps() -> tuple[int, int, int]:
+    """(min_fit, max_drafts, daily_cap) — env > karani.toml > defaults.
+    The daily cap is what makes hourly scheduling safe: 24 runs/day
+    share one budget, they don't multiply it."""
+    from karani.config import get_config
+    from karani.config.loader import resolve
+    ac = get_config().autopilot
+    return (int(resolve("AUTOPILOT_MIN_FIT", ac.min_fit, 85)),
+            int(resolve("AUTOPILOT_MAX_DRAFTS", ac.max_drafts, 3)),
+            int(resolve("AUTOPILOT_MAX_DRAFTS_PER_DAY",
+                        ac.max_drafts_per_day, 5)))
+
+
+@dataclass
+class AutopilotStats:
+    candidates: int = 0
+    drafted: int = 0
+    delivered: int = 0
+    budget_left: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+async def run_autopilot(
+    storage: Storage, *,
+    slack, channel: str,
+    make_qualifier=None, load_resume=None,
+    min_fit: int | None = None,
+    max_drafts: int | None = None,
+    daily_cap: int | None = None,
+) -> AutopilotStats:
+    """Draft + deliver packs for the top candidates, bounded twice:
+    `max_drafts` per run AND `daily_cap` per UTC day across all runs."""
+    from karani.drafting import build_application_pack
+    from karani.slackbridge.blocks import pack_blocks
+
+    cfg_min_fit, cfg_max, cfg_daily = _caps()
+    min_fit = cfg_min_fit if min_fit is None else min_fit
+    max_drafts = cfg_max if max_drafts is None else max_drafts
+    daily_cap = cfg_daily if daily_cap is None else daily_cap
+
+    stats = AutopilotStats()
+    if max_drafts <= 0:
+        log.info("autopilot disabled (AUTOPILOT_MAX_DRAFTS<=0)")
+        return stats
+
+    spent_today = await storage.drafts_today()
+    budget = min(max_drafts, max(0, daily_cap - spent_today))
+    stats.budget_left = max(0, daily_cap - spent_today)
+    if budget <= 0:
+        log.info("autopilot daily budget spent (%d/%d today)",
+                 spent_today, daily_cap)
+        return stats
+
+    rows = await storage.autopilot_candidates(min_fit=min_fit,
+                                              limit=budget)
+    stats.candidates = len(rows)
+    if not rows:
+        return stats
+
+    resume = load_resume()
+    client = make_qualifier() if make_qualifier else None
+    for row in rows:
+        job_id = row["id"]
+        try:
+            pack = await build_application_pack(
+                client, storage, job_row=row,
+                resume_markdown=resume.raw_markdown,
+            )
+            if pack.failed:
+                # Malformed LLM output: never deliver a broken pack, and
+                # leave the job in the candidate pool so the next pass
+                # retries it (build_application_pack records nothing on
+                # failure).
+                stats.errors.append(f"job_id={job_id}: draft failed "
+                                    f"(malformed LLM output); will retry")
+                continue
+            stats.drafted += 1
+            await slack.post_message(
+                channel,
+                f"Application pack ready for review: "
+                f"{row.get('company_display')} — {row.get('title')}",
+                blocks=pack_blocks(row, pack.pkg,
+                                   artifacts=pack.artifacts,
+                                   voice=pack.voice),
+            )
+            stats.delivered += 1
+            await maybe_sync_job(storage, job_id)
+        except Exception as exc:
+            stats.errors.append(f"job_id={job_id}: {exc}")
+            log.exception("autopilot failed for job %s", job_id)
+    return stats