talanton 0.5.0__tar.gz

talanton-0.5.0/.claude/commands/draft-role.md

@@ -0,0 +1,78 @@
+---
+description: Interview the operator about an open role and write its position file
+---
+
+Write a new position file. Do not start from a template dump — interview first,
+draft second.
+
+One YAML holds the ad copy, the knockouts and the rubric together, because they
+are the same decision written three ways. Change what the role requires and the
+ad, the screening standard and the questions candidates get asked all move with
+it. That is the point of the format, so fill in all three or none.
+
+## 1. Interview
+
+Ask only what you cannot infer, a few questions at a time. You need:
+
+- What the person will actually do in their first six months. Push for
+  specifics; "work on our AI platform" is not something you can screen against.
+- What makes a candidate an obvious no, and what makes one an obvious yes.
+- Seniority, salary band, employment type, workplace (onsite / hybrid /
+  remote), and for remote, which countries are acceptable.
+- Where applications should arrive. Each position gets its own address, or one
+  address with a plus tag — that is how an application is routed to the right
+  role without anyone setting an environment variable.
+- When the role closes.
+
+If the operator resists naming a salary band, say that omitting it costs reach —
+indexers rank salaried postings higher and candidates filter on it — then
+respect their answer.
+
+## 2. Write it
+
+Create `<store>/positions/<id>.yaml`, modelled on
+[`example/openings/ai-engineer.yaml`](../../example/openings/ai-engineer.yaml).
+The `id` is lowercase-hyphenated and is never reused for a different role.
+
+Write `pitch` as prose for the candidate you want, not a list of technologies.
+Concrete detail: team size, who they report to, what the first project is.
+Generic postings attract generic applicants.
+
+Keep `requirements` short and testable. Every line must be something you could
+later check against a CV. If you cannot check it, it belongs in the pitch or
+nowhere.
+
+## 3. Write the rubric, and be careful with knockouts
+
+The rubric must be specific enough that two readers would score the same CV
+within a point of each other. For each dimension: what it measures, what a 2, a
+5 and an 8 look like concretely, and its weight.
+
+**A knockout removes a person from the process entirely, in code.** A candidate
+who fails one is filtered out of every listing the agent can see and never
+reaches a digest — that is enforced in `screening.py`, not left to a prompt. So:
+
+- Only write a knockout the operator has explicitly asked for.
+- Only write one that is genuinely pass/fail and could never be compensated for.
+- Prefer a scored dimension. Say so if you are choosing one over a knockout.
+
+`screening.min_score` is the other filter and it is opt-in. Leave it out unless
+the operator asks; a floor set too high discards people quietly.
+
+Add `must_not_influence`: name, gender, nationality beyond the right to work,
+age, photograph, university prestige as a proxy for ability. This is not
+decoration; it is what the rubric is for.
+
+## 4. Validate and show the ads
+
+```bash
+talanton positions
+talanton ads <id>
+```
+
+Fix every error. Read the board `setup` notes aloud the first time a board is
+used, and flag any `!!` length warning — those mean a human has to decide what
+to cut. Nothing here posts anything anywhere; pasting is the operator's job.
+
+Report what you wrote, which knockouts you chose and why, and what still needs
+their answer.

talanton-0.5.0/.claude/commands/hiring-cycle.md

@@ -0,0 +1,88 @@
+---
+description: Run the recruitment cycle by hand, one stage at a time, and report what happened
+---
+
+Run the cycle manually and show your work. Two stages do the actual work, and
+neither needs a mailbox.
+
+```bash
+export TALANTON_CONFIG=./talanton.toml   # or hiring/talanton.toml
+```
+
+## 0. Look before you touch
+
+```bash
+talanton check
+talanton status
+```
+
+`check` must pass first. `status` reads the two locations directly — no model,
+no mailbox, no cost — and tells you how many CVs are waiting and who has
+already been assessed.
+
+## 1. Get CVs into the CVs location
+
+Either someone drops them in, or:
+
+```bash
+talanton inbox     # what is unread. marks nothing, sends nothing
+talanton fetch     # mailbox -> CVs folder
+```
+
+`fetch` cannot send: no SMTP path, and no import path to one — a test walks the
+import graph to keep it that way. Nothing a candidate writes can provoke a
+reply, however it is phrased. It makes no model call either.
+
+Report what arrived, and anything that could not be read.
+
+## 2. Assess
+
+```bash
+talanton assess <role>
+```
+
+Every CV without an assessment is read against the position's rubric, and the
+assessment is written to the assessments location. **An assessment that is not
+saved does not exist** — if the output does not say assessments were saved,
+that is the bug; check `talanton status` before going on.
+
+Two things to watch for and report honestly:
+
+- **Unreadable CVs are not zeros.** A scanned PDF with no text layer must be
+  reported by filename, never scored. If you see one scored, stop.
+- **Knockout failures are filtered here, in code.** Check who:
+
+```bash
+talanton status <role>
+```
+
+Read any one of them in full with:
+
+```bash
+talanton show <candidate-id>
+```
+
+If the filter caught someone it should not have, that is a rubric problem. Say
+so, name the id, and use `/review-filter`. Do not route around the filter.
+
+## 3. Shortlist
+
+```bash
+talanton shortlist <role>
+```
+
+Sends the operator who is worth reading — **by candidate id, with a link to
+each CV, never a name.** Identity lives behind the link, where folder
+permissions decide who may learn it. A summary containing a name is refused by
+the tool, not quietly sent.
+
+If nobody clears the bar, nothing is sent and it says so. A quiet week is a
+useful result, not a failure — do not lower the bar to produce a shortlist.
+
+## 4. Report
+
+How many CVs arrived, how many were assessed, how many were unreadable and
+which files, how many the filter held back and on what, and who was surfaced.
+
+Nothing here can contact a candidate, and you must not try to. If a CV leaves a
+question open, put the question in the shortlist so a person can ask it.

talanton-0.5.0/.claude/commands/review-filter.md

@@ -0,0 +1,58 @@
+---
+description: Audit who the knockout filter removed, and propose a rubric change if it was wrong
+---
+
+The filter removes people before a human sees them. That is the whole value of
+it and also the whole risk, so it gets audited deliberately rather than
+whenever someone remembers.
+
+## 1. See who it caught
+
+```bash
+talanton status <role>
+```
+
+Every filtered candidate is listed with the reason. If nobody was filtered, say
+so and stop.
+
+## 2. For each one, decide what actually failed
+
+Read the assessment's `facts` block against the CV. This is why facts are
+recorded separately from scores.
+
+- **Reading failure** — the facts are wrong. The assessment recorded
+  `work_permit: fail` because it read a student visa as no right to work. The
+  rubric is fine; the extraction is not. Fix how the knockout is worded so it is
+  unambiguous, and re-screen. Changing the rubric here would be compensating for
+  a parsing bug by distorting the criteria.
+- **Rubric failure** — the facts are right and the exclusion is still wrong. The
+  knockout is drawn in the wrong place.
+
+Say which one you concluded, and why. If you cannot tell, ask.
+
+## 3. Show the cost before proposing anything
+
+A knockout cannot be compensated for by strength elsewhere, so state plainly
+what it removed:
+
+> the `academic-only` knockout excluded 4 assessed candidates, including one
+> scoring 8.5
+
+That sentence is what stops a bad rubric change. Then propose the edit as a diff
+a person can argue with — thresholds and worked examples, not weights nudged by
+a tenth.
+
+## 4. On approval
+
+Bump `version` in the position file, commit with the candidates that motivated
+the change named in the message, and re-screen the pool so the new standard
+applies to everyone rather than only to whoever arrives next.
+
+Report who moved. "Two previously filtered now clear it" is the payoff for
+keeping records, and it means an early miscalibration is recoverable rather
+than a set of people you silently lost.
+
+Never adjust a score or a threshold outside this path, and never feed past
+decisions into the screening prompt as examples — that is a model quietly
+learning preferences nobody wrote down, and it destroys both the audit trail
+and the claim that the rubric was applied uniformly.

talanton-0.5.0/.env.example

@@ -0,0 +1,23 @@
+# Secrets and deployment only. Everything else lives in talanton.toml.
+# Copy to .env. Gitignored — keep it that way.
+
+# The apply mailbox (read-only side). An app password, not the account password.
+# Paste it exactly as Google shows it: the spaces in "abcd efgh ijkl mnop" are
+# display only and are stripped for you.
+TALANTON_INBOUND_PASSWORD=
+
+# The sending identity — a DIFFERENT account, with no access to the mailbox
+# above. Only needed once dry_run is off.
+TALANTON_OUTBOUND_PASSWORD=
+
+# Vertex. Model access is application default credentials; there is no API key.
+GOOGLE_GENAI_USE_ENTERPRISE=TRUE
+GOOGLE_CLOUD_PROJECT=
+GOOGLE_CLOUD_LOCATION=europe-west6
+
+# Optional overrides, for deployment where a config file is awkward.
+# TALANTON_CONFIG=/etc/talanton/talanton.toml
+# TALANTON_STORE=/var/hiring
+# TALANTON_OPERATORS=hiring@example.com
+# TALANTON_ALLOW_DOMAINS=example.com
+# TALANTON_DRY_RUN=0

talanton-0.5.0/.github/workflows/check.yml

@@ -0,0 +1,38 @@
+name: check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev --extra gdrive --extra gcs
+
+      - name: lint and format
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: types
+        run: uv run mypy
+
+      - name: tests
+        run: uv run pytest -q
+
+      - name: the engine itself has no candidate data and no deployment config
+        run: uv run talanton check
+
+      # The example is a real, runnable deployment against invented CVs. If it
+      # stops checking out, the first thing anybody tries is broken.
+      - name: the example deployment checks out and renders its ads
+        run: |
+          uv run talanton --config example/talanton.toml check
+          uv run talanton --config example/talanton.toml status
+          uv run talanton --config example/talanton.toml ads ai-engineer > /dev/null

talanton-0.5.0/.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Candidate data must never land in the engine repository. These are the
+# default location names, so a stray run in this checkout cannot commit anyone.
+data/
+candidates/
+/cvs/
+/assessments/
+example/assessments/
+
+# A real deployment config at the root is a company's, not the engine's.
+# Rooted, so example/talanton.toml — which CI renders against — still ships.
+/talanton.toml

talanton-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+# Install once:  uv run pre-commit install
+# Run on everything:  uv run pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=512]
+      # A CV or an assessment must never be committed to this repository.
+      - id: check-case-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+      - id: mypy
+        files: ^talanton/
+        additional_dependencies: [types-PyYAML]
+
+  # Candidate data and credentials are the two things that must not land here.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks