seektalent 0.2.4

Local CLI Agent for deterministic multi-round resume matching with Pydantic AI

SeekTalent

English

SeekTalent is an experimental local-first resume matching engine. It turns a job description and optional sourcing notes into a deterministic multi-round shortlist using requirement extraction, controlled CTS retrieval, per-resume scoring, reflection, and finalization.

The current product shape is intentionally narrow:

• the primary product is a local CLI
• the same runtime can also be imported as a Python dependency
• a minimal local web UI still exists, but it is secondary

Highlights

• Installable CLI with stable subcommands: run, init, doctor, version, update, inspect
• Stable Python entrypoints: run_match(...) and run_match_async(...)
• Structured run artifacts written under runs/ by default
• Explicit model configuration using provider:model
• Real CTS integration with explicit credential requirements

Quick Start

Prerequisites

• Python 3.12+
• one supported LLM provider credential
• CTS credentials for real CTS mode

Install as a CLI

From a local checkout:

uv build
pipx install dist/seektalent-0.2.4-py3-none-any.whl

If you prefer a plain Python environment:

pip install dist/seektalent-0.2.4-py3-none-any.whl

Create a starter env file

seektalent init

Fill the required values in .env

At minimum:

OPENAI_API_KEY=your-openai-key
SEEKTALENT_CTS_TENANT_KEY=your-cts-tenant-key
SEEKTALENT_CTS_TENANT_SECRET=your-cts-tenant-secret

If you keep the default openai-responses:* models, OPENAI_API_KEY is the only provider key you need.

Validate the local setup

seektalent doctor

Recommended black-box workflow

seektalent --help
seektalent doctor
seektalent run --jd-file ./jd.md
seektalent inspect --json
seektalent update

Run one workflow

seektalent run \
  --jd "Python agent engineer with retrieval and ranking experience"

Add notes when you want to inject sourcing preferences or exclusions:

seektalent run \
  --jd "Python agent engineer with retrieval and ranking experience" \
  --notes "Shanghai preferred, avoid pure frontend profiles"

Canonical output is human-readable. For wrappers and scripts, use machine output:

seektalent run \
  --jd "Python agent engineer" \
  --notes "Shanghai preferred" \
  --json

Print upgrade instructions

seektalent update

Inspect the published CLI contract

seektalent inspect --json

Install Paths

Terminal users

Recommended:

pipx install dist/seektalent-0.2.4-py3-none-any.whl

This gives you the seektalent command directly.

Python integrators

pip install dist/seektalent-0.2.4-py3-none-any.whl

Then:

from seektalent import run_match

result = run_match(
    jd="Python agent engineer",
)

print(result.final_markdown)
print(result.run_dir)

CLI

The canonical entrypoint is:

seektalent run --help

Available commands:

• seektalent run
• seektalent init
• seektalent doctor
• seektalent version
• seektalent update
• seektalent inspect

Recommended black-box sequence:

• seektalent --help
• seektalent doctor
• seektalent run
• seektalent inspect --json
• seektalent update

Key options on run:

• --jd or --jd-file for the required job description
• --notes or --notes-file for optional sourcing preferences
• --env-file
• --output-dir
• --json

The default output root is ./runs relative to the current working directory. Override it per run with:

seektalent run \
  --jd "Python agent engineer" \
  --notes "Shanghai preferred" \
  --output-dir ./outputs

Full CLI reference:

• docs/cli.md

Wrapping SeekTalent

Two supported wrapper patterns are intentionally stable:

Wrap the CLI

Run:

seektalent run --jd "..." --json

Then read the single JSON object from stdout.

Wrap the library

from seektalent import run_match

result = run_match(jd="...", notes="...")
payload = result.final_result.model_dump(mode="json")

Pass notes="..." when you want to add sourcing preferences; omit it when JD alone is enough.

Use this path when you want to build your own API server, desktop shell, or workflow wrapper around the runtime.

Configuration

Environment variables are read from .env by default. You will usually configure:

• provider credentials such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY
• CTS settings such as SEEKTALENT_CTS_BASE_URL, SEEKTALENT_CTS_TENANT_KEY, and SEEKTALENT_CTS_TENANT_SECRET
• runtime settings such as round limits, concurrency, and output directory

Full configuration reference:

• docs/configuration.md

Important rules:

• model variables must use the provider:model format
• OpenAI-family models require OPENAI_API_KEY
• anthropic:* requires ANTHROPIC_API_KEY
• google-gla:* requires GOOGLE_API_KEY

Web UI

The repository still includes a minimal local web UI:

• backend API: seektalent-ui-api
• frontend app: apps/web-user-lite
• default backend port: 8011
• default frontend port: 5176

Start the backend:

uv run seektalent-ui-api

Start the frontend in another terminal:

cd apps/web-user-lite
pnpm install
pnpm dev

Then open:

http://127.0.0.1:5176

Outputs

Each run creates a timestamped directory under runs/ by default, including files such as:

• trace.log
• events.jsonl
• run_config.json
• final_candidates.json
• final_answer.md
• per-round controller / retrieval / reflection / scoring artifacts

Output reference:

• docs/outputs.md

Limits

Current boundaries are intentional:

• this is an experimental local engine, not a hosted multi-tenant product
• the web UI is a thin local shim, not a full recruiting platform
• the CTS adapter is scoped to the fields and semantics implemented in this repository
• the runtime is built for auditable deterministic control flow, not open-ended autonomous tool use

Docs

• Configuration
• CLI
• UI
• Outputs
• Architecture
• Development

Historical versioned design notes remain under docs/v-*.

License

This project is licensed under the GNU Affero General Public License v3.0.

See LICENSE.