karani 0.3.0__tar.gz

karani-0.3.0/.circleci/config.yml

@@ -0,0 +1,83 @@
+# CircleCI mirror of .github/workflows/ci.yml — same commands, same gates.
+# Publishing stays on GitHub Actions (publish.yml): PyPI Trusted
+# Publishing is not available from CircleCI, and we do not store PyPI
+# tokens in third-party CI secrets.
+#
+# One-time setup: circleci.com -> log in with GitHub -> Set Up Project
+# for cod3smith/karani -> use this config. For the coverage badge, add
+# COVERALLS_REPO_TOKEN in Project Settings -> Environment Variables
+# (token from coveralls.io repo page).
+version: 2.1
+
+executors:
+  py:
+    parameters:
+      tag:
+        type: string
+    docker:
+      - image: cimg/python:<< parameters.tag >>
+
+commands:
+  install:
+    steps:
+      - checkout
+      - run:
+          name: Install uv + project (all extras)
+          command: |
+            pip install --quiet uv
+            uv sync --all-extras
+
+jobs:
+  test:
+    parameters:
+      tag:
+        type: string
+    executor:
+      name: py
+      tag: << parameters.tag >>
+    steps:
+      - install
+      - run:
+          name: Lint
+          command: uv run ruff check karani tests
+      - run:
+          name: Tests (with coverage)
+          command: >
+            uv run pytest tests -q
+            --cov=karani --cov-report=lcov:coverage.lcov --cov-report=term
+      - run:
+          name: Coveralls (3.13 only, when token configured)
+          command: |
+            if [ "<< parameters.tag >>" = "3.13" ] && [ -n "$COVERALLS_REPO_TOKEN" ]; then
+              uv run --with coveralls coveralls --service=circleci
+            else
+              echo "skipping coveralls upload"
+            fi
+
+  build:
+    executor:
+      name: py
+      tag: "3.13"
+    steps:
+      - checkout
+      - run:
+          name: Build wheel + sdist
+          command: |
+            pip install --quiet uv
+            uv build
+      - run:
+          name: Smoke-test the wheel
+          command: |
+            uv venv /tmp/smoke
+            uv pip install --python /tmp/smoke/bin/python dist/*.whl
+            /tmp/smoke/bin/karani --version
+            KARANI_HOME=/tmp/kh /tmp/smoke/bin/karani init --yes
+            KARANI_HOME=/tmp/kh KARANI_CONFIG=/tmp/kh/karani.toml \
+              /tmp/smoke/bin/karani config check
+
+workflows:
+  ci:
+    jobs:
+      - test:
+          tag: "3.13"
+      - build

karani-0.3.0/.env.example

@@ -0,0 +1,27 @@
+# karani secrets — copy to .env and fill in. NEVER commit .env.
+# Everything non-secret (what to hunt, providers, endpoints, channels)
+# lives in karani.toml — create yours with: karani init
+
+# Postgres. Unset = in-memory storage (state lost between runs).
+DATABASE_URL=postgresql://karani:karani@localhost:5433/karani
+
+# LLM provider keys — only the provider(s) you use in karani.toml [llm].
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+# ANTHROPIC_API_KEY=sk-ant-...
+# (provider "local" needs no key — any OpenAI-compatible server)
+
+# Slack (two-way surface; channel id lives in karani.toml [slack])
+# SLACK_BOT_TOKEN=xoxb-...        # OAuth & Permissions -> Bot User OAuth Token
+# SLACK_APP_TOKEN=xapp-...        # Basic Information -> App-Level Tokens
+
+# Notion mirror (database id lives in karani.toml [notion])
+# NOTION_TOKEN=ntn_...            # notion.so/my-integrations
+
+# MinIO artifact store (endpoint lives in karani.toml [artifacts])
+# MINIO_ACCESS_KEY=karani
+# MINIO_SECRET_KEY=karani-local-secret
+
+# Machine knobs (optional)
+# RESUME_PATH=data/resume.md
+# HTTP_CONCURRENCY=6
+# STALE_JOB_DAYS=10

karani-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --all-extras
+      - name: Lint
+        run: uv run ruff check karani tests
+      - name: Tests (with coverage)
+        run: >
+          uv run pytest tests -q
+          --cov=karani --cov-report=lcov:coverage.lcov --cov-report=term
+      - name: Coveralls
+        if: matrix.python-version == '3.13'
+        uses: coverallsapp/github-action@v2
+        with:
+          file: coverage.lcov
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Smoke-test the wheel
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke/bin/python dist/*.whl
+          /tmp/smoke/bin/karani --version
+          KARANI_HOME=/tmp/kh /tmp/smoke/bin/karani init --yes
+          KARANI_HOME=/tmp/kh KARANI_CONFIG=/tmp/kh/karani.toml \
+            /tmp/smoke/bin/karani config check

karani-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: publish
+
+# Publishes to PyPI on a GitHub release, via PyPI Trusted Publishing
+# (OIDC) — no API token stored in repo secrets. One-time setup on
+# pypi.org: project karani -> Publishing -> add this repo + workflow.
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

karani-0.3.0/.gitignore

@@ -0,0 +1,30 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Env / secrets
+.env
+.env.local
+*.pem
+
+# OS noise
+.DS_Store
+
+# Personal data — resume.md.example is the committed template
+data/resume.md
+
+# Generated output
+data/digest.html
+drafts/
+logs/
+
+# Personal hunt configuration — karani.example.toml ships in the wheel
+karani.toml
+.env.backup

karani-0.3.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "karani": {
+      "command": "uv",
+      "args": ["run", "karani", "mcp"]
+    }
+  }
+}

karani-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13

karani-0.3.0/CLAUDE.md

@@ -0,0 +1,363 @@
+# CLAUDE.md — karani
+
+This file is the entry point for any Claude Code (or coding-agent) session on this
+repo. Read it first, then follow the pointers into `docs/` for depth.
+
+If you change something material — architecture, positioning, a public interface,
+or a rule below — update this file in the same commit. Docs drift is worse than
+no docs.
+
+---
+
+## 1. What this is
+
+**karani** is a semi-autonomous, personal job-application pipeline for **Kelyn
+Njeri** (Nairobi-based senior/staff engineer with a data-platform + causal-ML
+background). It:
+
+1. **Ingests** postings from 9 sources (Greenhouse, Lever, Ashby, Workable,
+   RemoteOK, Himalayas, We Work Remotely, Remotive, aijobs.net).
+2. **Pre-filters** deterministically for role fit + seniority + geo + comp +
+   skill overlap. Drops ~95% before any LLM call.
+3. **Qualifies** survivors against Kelyn's resume via LLM (OpenRouter →
+   `moonshotai/kimi-k2-thinking` by default; single-turn or tool-using agent
+   loop). Emits `fit_score`, `verdict`, evidence-backed strengths, gaps,
+   recommended positioning.
+4. **Digests** the shortlist as HTML / markdown / text.
+5. **Drafts** cover letters + tailored bullets + application-question answers
+   in Kelyn's voice.
+6. **Tracks** the application through a state machine (drafting → applied →
+   interviewing → offer/rejection).
+7. **Learns** from Kelyn's reactions via a `user_verdict` feedback loop that
+   feeds past pairs back as few-shot examples on the next qualify run.
+8. **Serves** the whole pipeline as an MCP server (`karani/mcp_server/`, stdio) so
+   MCP clients can drive ingest/qualify/shortlist/draft/track
+   conversationally. See `docs/adrs/0008-mcp-server-interface.md`.
+9. **Remembers** distilled facts (preferences, company intel, outcomes)
+   in a ledger-first memory layer (`karani/memory/`) and injects them into
+   qualification. mem0 + pgvector optional upgrade. See `docs/memory.md`.
+10. **Converses** over Slack (`karani/slackbridge/`, Socket Mode): pushes the
+    digest/worklist and takes the same verbs back (`verdict 123 apply`,
+    `prep 45`). See `docs/adrs/0010-slack-two-way-surface.md`.
+11. **Mirrors** tracked applications onto a Notion board
+    (`karani/notionsync/`), updated live on every state change and reconciled
+    by the scheduled run. See `docs/adrs/0011-notion-mirror.md`.
+12. **Hunts** continuously (`karani/autopilot/`, `karani hunt`): drafts packs
+    for top-fit roles unattended (fit floor + per-run cap) and delivers
+    Slack review cards with Approve/Skip/Applied buttons. Never submits
+    — see `docs/adrs/0012-autopilot-draft-human-send.md`.
+13. **Converts**: fast-lane flags on fresh high-fit roles, ATS keyword
+    coverage per draft, cached company dossiers (`karani/intel/`), warm-path
+    candidates, interview prep packs, and dossier-hooked follow-ups —
+    all measured through `funnel_stats` (roadmap Tier 1.5).
+
+**Positioning:** two role shapes qualify — (1) *companies that hire
+globally at SF pay bands regardless of candidate location*, and
+(2) *roles that sponsor a visa + relocation, EU and Japan preferred*
+(local top-of-market comp acceptable there). Target roles: software
+engineering, research engineering, ML/AI — computational-bio roles are
+excluded. See `docs/vision.md`.
+
+---
+
+## 2. Repo layout
+
+```
+karani/                              (repo)
+├── CLAUDE.md                        ← you are here
+├── README.md                        ← human quickstart (pip install karani)
+├── pyproject.toml                   ← PyPI package `karani`; `karani` CLI script
+├── Makefile                         ← thin dev aliases over the karani CLI
+├── karani.example.toml              → shipped in-wheel; see karani/resources/
+├── .env.example                     ← secrets template (keys live in env, never toml)
+│
+├── karani/                          ← THE installable package
+│   ├── cli.py                       ← `karani <verb>` — ~30 verbs, single entry point
+│   ├── config/                      ← karani.toml schema + loader + `karani init` wizard (ADR 0015)
+│   ├── resources/                   ← compose file, launchd templates, example toml (in-wheel)
+│   ├── ingestion/                   ← fetch → classify → pre-filter → store → sweep
+│   │     (config.py signals · profile.py · filters.py · roles.py · storage.py ·
+│   │      targets.py · orchestrator.py · digest.py · discovery.py · resume.py ·
+│   │      per-source fetchers: greenhouse/lever/ashby/workable + 5 feeds)
+│   ├── qualification/               ← LLM fit tier: prompts (versioned) · client ·
+│   │     providers (openrouter/anthropic/local) · factory (per-task routing) ·
+│   │     tools + agent loop · runner
+│   ├── drafting/                    ← pack factory: pipeline.py (draft→humanize→
+│   │     tailor→store, ALL surfaces) · keywords · humanize · resume_tailor ·
+│   │     prep · followup · writers
+│   ├── intel/                       ← cached company dossiers + warm paths (TTL 14d)
+│   ├── memory/                      ← ledger-first memory, mem0 optional (docs/memory.md)
+│   ├── slackbridge/                 ← two-way Slack: client/blocks/commands/
+│   │     interactions (pack buttons)/listener (ADR 0010)
+│   ├── notionsync/                  ← Notion board mirror, schema-adopting (ADR 0011)
+│   ├── autopilot/                   ← continuous hunt: pack + review card (ADR 0012)
+│   ├── orchestration/               ← LangGraph hourly pass (ADR 0013)
+│   ├── artifacts/                   ← MinIO/S3 per-job objects + presigned links (ADR 0014)
+│   └── mcp_server/                  ← MCP interface, 25 tools, thin adapter (ADR 0008)
+│
+├── docker-compose.yml               ← dev infra (pgvector db :5433, minio :9010, ollama)
+├── data/                            ← resume.md (yours, gitignored) + .example
+├── drafts/                          ← generated packs (gitignored)
+├── tests/                           ← 192+ deterministic tests (no network, no clock)
+└── docs/                            ← vision · architecture · roadmap · memory ·
+      conventions · operations · adrs/ (0001-0015)
+```
+
+---
+
+## 3. Getting oriented in 60 seconds
+
+```bash
+# One-time setup
+uv sync                                        # or pip install -e .
+uv sync --extra dev                            # + pytest
+cp .env.example .env                           # fill DATABASE_URL, OPENROUTER_API_KEY
+cp data/resume.md.example data/resume.md       # edit it — this is YOU
+
+# Daily loop
+karani hourly                                  # one full hunt pass
+open data/digest.html                          # or send it to yourself
+
+# Act on a suggestion
+karani draft 12345            # writes drafts/*.md
+karani status 12345 applied
+karani verdict 12345 apply    # feeds the taste-calibration loop
+
+# Or drive it all over MCP (Claude Code picks up .mcp.json automatically)
+karani mcp                                     # MCP server (stdio)
+```
+
+Full CLI reference is in `README.md`. Full command surface is in `Makefile`.
+
+---
+
+## 4. Non-negotiable rules
+
+These aren't preferences — they're guardrails you must respect. Break one, and
+you'll silently degrade the pipeline in a way that's hard to spot.
+
+### 4.1 Never regress the SF-band, global-remote thesis
+- `ingestion/config.py` signals are named `global_hire_*`, `regional_restriction_*`,
+  `pay_parity_*`. **Do not** reintroduce Kenya-specific names — they're the whole
+  reason the pipeline exists, but the *filter* is location-agnostic (a US-only
+  role gets vetoed whether Kelyn's in Nairobi, Berlin, or Buenos Aires).
+- `min_comp_usd` default is $160k. Below that = not SF-band = drop.
+- **Extension (2026-08, prompts qual-v3):** `relocation_signals` soften
+  geo/onsite vetos — a region-locked or onsite role that sponsors visa +
+  relocation (EU/Japan preferred) goes to the LLM instead of being
+  dropped, and the LLM may accept local top-of-market comp for those.
+  This *adds* a second qualifying shape; it does not weaken shape one.
+
+### 4.2 Signal matching is word-boundary anchored
+- Use `_find_signal` in `filters.py` (or the `_wb()` helper in `roles.py`).
+- **Never** substring-match location or role phrases. "us only" matches "campus
+  only" as a substring — that's the exact bug that made the pipeline useless
+  before the refactor. There's a regression test in `tests/test_filters.py`.
+
+### 4.3 Comp parsing requires a currency anchor
+- `_parse_comp` in `filters.py` only accepts a number band when a currency /
+  comp keyword is within 40 chars. Do not weaken this — you'll parse "5-10
+  years experience" as $5k-$10k and hard-fail every role.
+
+### 4.4 Content hash is normalized
+- `Job.compute_hash` lowercases + strips punctuation + collapses whitespace
+  before hashing. If you change the hash inputs, previously-qualified jobs
+  will *all* re-qualify (billed). If that's intentional, say so in the commit.
+
+### 4.5 Every fetcher must go through `get_with_retry`
+- `ingestion/base.py`. Enforces per-host semaphore + tenacity backoff + 404
+  fast-fail. Do not write a fetcher that calls `client.get` directly.
+
+### 4.6 Every fetched `Job` must call `.finalize()`
+- Populates `content_hash` and `canonical_hash`. Without these, upsert dedup
+  and cross-source dedup silently break.
+
+### 4.7 Storage schema changes go through `ALTER TABLE ... IF NOT EXISTS`
+- `ingestion/storage.py` runs the `SCHEMA` block on every connect. It's
+  idempotent. Never write a destructive migration — Kelyn's Neon DB has
+  history in it now.
+
+### 4.8 Credentials come from env vars only
+- `config.py` reads `os.getenv(...)`. Never hardcode a DSN, API key, or token
+  in code. The `.env.example` shows the shape.
+
+### 4.9 The pre-filter is deterministic
+- No LLM calls in `filters.py` or `roles.py`. That's the whole point of the
+  tier split — pre-filter is free and fast, qualification is billed. Don't
+  cross the streams.
+
+### 4.10 Prompts are versioned
+- `qualification/prompts.py` has `PROMPT_VERSION`, `AGENT_PROMPT_VERSION`.
+  `drafting/prompts.py` has `DRAFT_PROMPT_VERSION`. Bump them when you
+  materially change a prompt — persisted `QualificationResult` rows carry
+  the version, and that's how we distinguish "old data" from "new data" for
+  A/B and rollback.
+
+### 4.11 The memory ledger is the system of record
+- The `memories` table in Postgres is ground truth; the mem0/pgvector
+  index is derived and disposable. Never write memory only to mem0, and
+  never let a mem0 failure abort a batch — degrade to `basic` recall.
+  See `docs/memory.md` and ADR 0009.
+- Memory writes happen on explicit events (verdict, outcome, deliberate
+  `remember`) — never auto-extracted from arbitrary LLM output.
+
+---
+
+## 5. Coding conventions
+
+Full details in `docs/conventions.md`. The one-liners:
+
+- **Python 3.11+**, no exceptions.
+- **Async everywhere** in ingestion + qualification. Blocking `time.sleep` or
+  sync `requests` calls will break the concurrency model.
+- **Pydantic v2** for every structured payload that crosses a boundary.
+- **`from __future__ import annotations`** at the top of every module.
+- **Type hints everywhere.** Use `dict`, `list`, `str | None` — not
+  `Dict`, `List`, `Optional`.
+- **Guard optional imports.** `qualification/anthropic.py` imports the
+  Anthropic SDK inside `__init__` so the module loads even when the SDK
+  isn't installed. Follow the same pattern for any future optional dep.
+- **Errors from LLMs are recoverable.** `qualify_one` on malformed JSON
+  downgrades to `verdict="maybe"` with a `why_skip` explanation. Never let
+  a bad LLM response throw and kill a batch.
+- **No emojis in code or docs** unless explicitly requested.
+
+---
+
+## 6. Testing conventions
+
+- Run: `make test` or `uv run pytest tests -q`. CI runs the same
+  suite + ruff + a wheel smoke on 3.11/3.12/3.13, with coverage to
+  Coveralls (`.github/workflows/ci.yml`).
+- Every new module needs a smoke test at minimum.
+- All 158 existing tests are deterministic (no network, no clock). Keep it
+  that way — use fake clients for LLM calls (see `tests/test_qualification.py`
+  and `tests/test_agent.py`), and `httpx.MockTransport` for HTTP (see
+  `tests/test_e2e_pipeline.py`).
+- MCP tools are tested through `app.call_tool` — full validation +
+  execution + serialization, no transport (see `tests/test_mcp_server.py`).
+- **conftest.py strips all external-service credentials** (Notion, Slack,
+  DATABASE_URL) before any module loads, plus an autouse re-strip per
+  test. Best-effort integrations read env at call time — without the
+  strip, the developer's real .env makes "deterministic" tests write to
+  live services (this happened: 30 fixture pages on the real Notion
+  board). A suite that suddenly runs slower than ~2s is doing network
+  I/O — treat that as a failure even when everything passes.
+- `pytest-asyncio` is auto-mode (see `pyproject.toml`). Just decorate coroutines
+  with `@pytest.mark.asyncio`.
+- The in-memory `Storage` fallback (`Storage("")`) is the standard test
+  substrate — no Postgres required.
+
+---
+
+## 7. Where to work next
+
+Prioritized list is in **`docs/roadmap.md`** with acceptance criteria per item.
+Summary:
+
+1. **Cron / scheduled runs** — `Makefile` is ready; wire it to `launchd`
+   (mac) or `systemd`/`cron` (linux). Half-day.
+2. **Neon credential rotation** — the DSN was in `config.py` at one point
+   before the refactor. Rotate it. 10 minutes on Kelyn's side, but has to
+   happen before real ops.
+3. **Persistent per-source health metrics** — right now the run stats are
+   ephemeral. Add a `source_runs` table + a `stats history` CLI. Half-day.
+4. **Digest as email / Slack / Cowork artifact** — HTML file exists. Wire
+   one delivery channel (SES, Slack webhook, or a Cowork artifact). Day.
+5. **Levels.fyi comp overlay** — where comp isn't disclosed, backfill via
+   a scrape/API. Feeds `fit_score`. Day.
+6. **Agent tool-use expansion** — add `check_glassdoor_reputation`,
+   `fetch_recent_news`, `check_engineering_blog_recency`. Half-day per tool.
+
+Bigger unlocks in `docs/roadmap.md`.
+
+---
+
+## 8. Where to find the "why" for decisions
+
+`docs/adrs/` — one file per key decision, why-based (context + decision +
+consequences). Don't argue architecture with the code; argue it with an ADR.
+If you're about to reverse a decision documented in an ADR, add a new ADR
+that supersedes it. Never delete.
+
+---
+
+## 9. Working with Kelyn
+
+- Kelyn is a **staff/principal-band engineer** (see `data/resume.md`). Talk
+  to him accordingly — skip explaining Python basics, but do explain
+  domain-specific tradeoffs (ATS quirks, prompt-engineering choices, DB
+  schema evolution).
+- Timezone: **EAT (UTC+3)**. Async-friendly.
+- Preferences: **concise, direct, no fluff, no emojis unless he asks.**
+  Prose over bullet lists in normal conversation; bullet lists for real
+  structured deliverables (this doc, roadmap, ADRs).
+- He'll push back if you sugar-coat. Be blunt about tradeoffs.
+
+---
+
+## 10. Fast paths for common tasks
+
+### Add a new ingestion source
+1. Add enum to `Source` in `ingestion/models.py`.
+2. Write `ingestion/<name>.py` — subclass `Fetcher`, use `get_with_retry`,
+   call `.finalize()` on every `Job`.
+3. Register in `ingestion/__init__.py:FETCHERS`.
+4. If per-company: add slugs to `TARGETS` in `targets.py`. If feed: add to
+   `FEED_SOURCES`.
+5. Write a test with a fake JSON payload.
+
+### Change what the pre-filter drops
+1. Edit `ingestion/filters.py` `pre_filter()`.
+2. Add / edit signals in `ingestion/config.py`.
+3. Add a regression test in `tests/test_filters.py`.
+4. If the change affects role classification: also touch `ingestion/roles.py`
+   and `tests/test_roles.py`.
+
+### Add a new LLM tool for the agent
+1. Add a function to `qualification/tools.py` — return text, wrap errors,
+   respect the byte cap.
+2. Append a `Tool(...)` entry to `DEFAULT_TOOLS`.
+3. Update the agent system prompt in `qualification/prompts.py`
+   (`AGENT_SYSTEM_PROMPT`) and bump `AGENT_PROMPT_VERSION`.
+4. Write a smoke test that scripts a `chat_turn` returning a `tool_calls`
+   block invoking your tool.
+
+### Add a new MCP tool
+1. Put any new query/mutation on `Storage` (or a runner) first — the MCP
+   layer stays a thin adapter, same as the CLI.
+2. Add an `@app.tool()` function in `mcp_server/server.py`. Raise `ToolError`
+   for expected user-input failures (plain exceptions get masked by the SDK).
+3. Add a test in `tests/test_mcp_server.py` via `app.call_tool`, and update
+   the tool-set assertion in `test_tool_listing`.
+4. If the tool mirrors a CLI verb, keep the two surfaces in sync.
+
+### Swap LLM providers
+1. Either set `QUAL_PROVIDER=anthropic|local` / `QUAL_MODEL=...` in env, or
+   pass `--provider` / `--model` to `qualify` and `draft`. `local` speaks to
+   any OpenAI-compatible server (Ollama/LM Studio/vLLM) — zero token cost;
+   recommended for bulk qualify, with a hosted model kept for drafting.
+2. To add a *new* provider: subclass into `qualification/<provider>.py`,
+   implement `complete()` (and `chat_turn()` if you want agent-mode
+   support), register in `qualification/factory.py`.
+
+---
+
+## 11. Things that look wrong but aren't
+
+- **`ingestion/sources.py` re-exports `FETCHERS` from `__init__.py`.** Legacy
+  compat shim. Don't delete without grep — external scripts might import
+  from there.
+- **`main.py` at root delegates to `ingestion.cli.main`.** Same reason.
+- **`comp_currency_original="USD"` when comp is undisclosed and unknown.**
+  Deliberate — the RemoteOK feed omits currency, so we accept as USD only
+  when the number falls in a plausible US-band range. See the docstring in
+  `remoteok.py`.
+- **`stages` is a JSONB append log, not a normalized `interview_stages`
+  table.** Deliberate simplicity — see `docs/adrs/`.
+
+---
+
+Last audit: this file must be re-read whenever any of the following change:
+`pyproject.toml`, `ingestion/config.py`, `ingestion/models.py`,
+`qualification/prompts.py`, or `docs/roadmap.md`.

karani-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to karani
+
+karani is a personal, semi-autonomous job-application pipeline built in
+public. Contributions are welcome — the architecture is deliberately
+modular so most changes touch one package.
+
+## Ground rules (read these first)
+
+1. **`CLAUDE.md` section 4 is non-negotiable.** Word-boundary signal
+   matching, deterministic pre-filter (no LLM calls in `filters.py`),
+   versioned prompts, ledger-first memory, idempotent schema migrations.
+   PRs that break a guardrail get closed with a pointer to the rule.
+2. **Karani never submits an application.** Anything that auto-submits,
+   auto-messages recruiters, or bypasses human review is out of scope —
+   see `docs/vision.md` non-goals and ADR 0012.
+3. **Argue architecture with ADRs, not code.** Reversing a documented
+   decision needs a superseding ADR in `docs/adrs/`.
+4. **Every surface stays in sync.** A new verb lands on `Storage`/runners
+   first, then CLI + MCP + Slack together (see ADR 0008/0010).
+
+## Setup
+
+```bash
+git clone <repo> && cd karani
+uv sync --all-extras
+cp .env.example .env                     # fill what you use; all optional
+cp data/resume.md.example data/resume.md # your resume — never committed
+make test                                # 181+ tests, ~2s, no network
+```
+
+The whole pipeline runs with zero external services (in-memory storage,
+`basic` memory mode). Postgres/Slack/Notion/MinIO/Ollama are additive.
+
+## Testing conventions
+
+- Deterministic only: no network, no clock. Fake LLM clients (see
+  `tests/test_qualification.py`), `httpx.MockTransport` for HTTP,
+  `Storage("")` for the DB. `conftest.py` strips all real credentials —
+  a suite that runs slower than ~2s is doing network I/O and is wrong.
+- Every new module needs at least a smoke test; every bugfix needs the
+  regression test that would have caught it.
+- MCP tools test through `app.call_tool`; Slack verbs through
+  `handle_command`; graph nodes through `build_hunt_graph` with fakes.
+
+## Where to start
+
+`docs/roadmap.md` is the single source of planned work, with acceptance
+criteria per item. Good first contributions:
+
+- **Tier 0 (production hardening)** — well-scoped, high-impact items
+  from the 2026-08 audit: cross-run dedup in candidate queries, advisory
+  locks around billed runs, a Postgres-marked test suite, heartbeat +
+  run/cost ledger, per-task model routing.
+- **A new ingestion source** — the most self-contained change there is;
+  recipe in `CLAUDE.md` section 10.
+- **Agent tools** (`qualification/tools.py`) — each tool is one function,
+  one registry entry, one smoke test.
+
+## PR checklist
+
+- [ ] `make test` green, `uv run ruff check` clean on touched files
+      (CI enforces both on 3.11–3.13 plus a wheel install smoke —
+      GitHub Actions and CircleCI run the same commands)
+- [ ] Guardrails in `CLAUDE.md` section 4 respected
+- [ ] Prompt changed materially? Version bumped
+- [ ] New capability? Landed on Storage/runner first, all surfaces synced
+- [ ] Docs updated in the same PR (`CLAUDE.md` rule: drift is worse than
+      no docs)

karani-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kelyn Njeri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.