Metadata-Version: 2.3
Name: seektalent
Version: 0.3.5
Summary: Packaged v0.3.3 runtime with an interactive CLI agent for resume search
Author: frankqdwang
Author-email: frankqdwang <wang15850317595@163.com>
License: GNU Affero General Public License v3.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pydantic-ai>=1.76.0
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: rich>=14.2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# SeekTalent

<p>
  <a href="#english"><img src="https://img.shields.io/badge/Language-English-0A66C2" alt="English"></a>
  <a href="./README.zh-CN.md"><img src="https://img.shields.io/badge/%E8%AF%AD%E8%A8%80-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-D4380D" alt="简体中文"></a>
</p>

## English

`SeekTalent` is currently on the `v0.3.3 active` runtime. `docs/v-0.3.3/` describes the active `HEAD` runtime and trace surfaces. `docs/v-0.3.2/` is kept as the frozen pre-cutover baseline for comparison. `HEAD` ships deterministic requirement normalization, the bootstrap core, persistent-anchor frontier control, reviewer-ready output, and checked-in offline artifacts.

What exists today:

- `docs/v-0.3.3/SYSTEM_MODEL.md` is the active canonical spec for `HEAD`
- `docs/v-0.3.3/IMPLEMENTATION_OWNERS.md` is the active implementation anchor for `HEAD`
- `docs/v-0.3.3/RUNTIME_SEQUENCE.md` is the active timing view of the runtime
- `docs/v-0.3.2/` remains frozen as the pre-cutover baseline
- `src/seektalent/models.py` holds the stable runtime contracts
- `src/seektalent/requirements/normalization.py` builds `SearchInputTruth` and normalized `RequirementSheet`
- `src/seektalent/bootstrap.py` runs the internal round-0 bootstrap flow
- `src/seektalent/retrieval/filter_projection.py` projects `SearchExecutionPlan_t` into CTS-safe native filters
- `src/seektalent/clients/cts_client.py` returns `RetrievedCandidate_t`
- `src/seektalent/retrieval/candidate_projection.py` builds `SearchExecutionResult_t`
- `src/seektalent/runtime/orchestrator.py` runs the full runtime loop and writes run artifacts
- `seektalent run` and `run_match(...)` return `SearchRunBundle`

What does not exist anymore:

- the old `v0.2` controller / reflection / scoring / finalize runtime
- prompt bundles and LLM wiring from `v0.2`
- compatibility aliases for deleted contracts

## Install

From a local checkout:

```bash
uv build
pipx install dist/seektalent-0.3.5-py3-none-any.whl
```

Or into an existing Python environment:

```bash
pip install dist/seektalent-0.3.5-py3-none-any.whl
```

## Quick Start

Write a starter env file:

```bash
seektalent init
```

`seektalent init` writes the bundled starter template that ships with the package. The repo-root [.env.example](/Users/frankqdwang/Agents/SeekTalent/.env.example) remains the authoring source for that template.

Minimal env values for real CTS mode:

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

Each of the 5 LLM callpoints can now be switched independently through `.env`. See [docs/configuration.md](/Users/frankqdwang/Agents/SeekTalent/docs/configuration.md).

Run the local rerank API:

```bash
uv run --group rerank seektalent-rerank-api
```

Check the local runtime surface:

```bash
seektalent doctor
seektalent inspect --json
```

Human-first entry:

```bash
seektalent
```

This opens an inline chat-first terminal session in a TTY. Paste the `JD`, press `Enter`, then optionally add `notes`. Use `Ctrl+J` for new lines. The whole run streams into one transcript, exits automatically after the final result, and leaves the session in terminal scrollback.

Agent-friendly entry:

```bash
seektalent run --request-file ./request.json --json --progress jsonl
```

Minimal request file:

```json
{
  "job_description": "Senior agent engineer with Python and LLM orchestration experience",
  "hiring_notes": "Shanghai preferred; startup background is a plus",
  "top_k": 10,
  "round_budget": 6
}
```

`run --json` still returns the full `SearchRunBundle`. The stable product result lives at `final_result.final_candidate_cards`.

## Python API

The package exports `run_match(...)` and `run_match_async(...)` and returns `SearchRunBundle`:

```python
from seektalent import AppSettings, run_match

result = run_match(
    job_description="Python agent engineer",
    hiring_notes="Shanghai preferred",
    settings=AppSettings(mock_cts=True),
    env_file=None,
)
print(result.final_result.stop_reason)
print(result.run_dir)
```

## Commands

- `seektalent` (TTY only; launches the one-shot chat-first terminal session)
- `seektalent run`
- `seektalent doctor`
- `seektalent init`
- `seektalent version`
- `seektalent update`
- `seektalent inspect`

## Docs

- [docs/v-0.3.3/SYSTEM_MODEL.md](docs/v-0.3.3/SYSTEM_MODEL.md)
- [docs/v-0.3.3/SYSTEM_MODEL.notion.md](docs/v-0.3.3/SYSTEM_MODEL.notion.md)
- [docs/v-0.3.3/IMPLEMENTATION_OWNERS.md](docs/v-0.3.3/IMPLEMENTATION_OWNERS.md)
- [docs/v-0.3.3/RUNTIME_SEQUENCE.md](docs/v-0.3.3/RUNTIME_SEQUENCE.md)
- [docs/v-0.3.2/SYSTEM_MODEL.md](docs/v-0.3.2/SYSTEM_MODEL.md)
- [docs/v-0.3.2/IMPLEMENTATION_OWNERS.md](docs/v-0.3.2/IMPLEMENTATION_OWNERS.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/configuration.md](docs/configuration.md)
- [docs/cli.md](docs/cli.md)
- [docs/outputs.md](docs/outputs.md)
- [docs/development.md](docs/development.md)
- [docs/_archive/v-0.3.1/implementation-checklist.md](docs/_archive/v-0.3.1/implementation-checklist.md)
