diff --git a/docs/plan-prompts-and-sources.md b/docs/plan-prompts-and-sources.md new file mode 100644 index 0000000..0d28e3c --- /dev/null +++ b/docs/plan-prompts-and-sources.md @@ -0,0 +1,57 @@ +# Plan: several prompts per agent, Swedish sources, Sources and gates UI + +Planned 2026-09-29. Five work packages with disjoint files, built in parallel worktrees made from `main`, merged by the planner. This file is folded into `decisions.md` and deleted when the work lands. + +## Why + +The owner's hunt spans three kinds of role (AI and data leadership, customer-facing technical leadership, AI research and innovation). One blended intent paragraph ranks a role by its distance to the blend, so a forward deployed lead role loses to a role that is a little of everything. The sources are engineering searches on Jobindex and boards of a seed list, so 4 of 16,841 open roles are Danish leadership roles, and 7 are in Malmö, Lund or Helsingborg. + +## Decisions + +**An agent is the group; it holds several prompts.** Votes, liked companies, gates, weights, limits and scores stay per agent, so a vote counts for every prompt of that agent. A second agent ("Market watch 1") has its own prompts and its own votes. No third level is added. + +**`fit` is the best prompt's fit.** Each prompt is embedded on its own; a role's fit is the maximum over the agent's prompts of the calibrated cosine. The name of the prompt that won is stored with the score. `taste` stays one vector per agent. + +**An agent's `intent` becomes its first prompt.** The migration moves every non-empty `agents.intent` into one prompt named after the agent. "An agent without an intent" now reads "an agent with no non-empty prompt". + +**Platsbanken is a third `search` provider.** The JobTech API (`https://jobsearch.api.jobtechdev.se/search`) needs no key, states a total, and filters by region concept id (Skåne län is `CaRE_1nn_cSU`). Checked live on 2026-09-29. + +**Teamtailor is read from the career site's public feed.** 32 of 362 seed companies and 9 of 30 Swedish ones sit on it. + +## Contracts between packages + +Agent JSON, in `GET /api/agents` and `POST /api/agents`: + +```json +{"id": 1, "name": "Wolf, next role", "prompts": [{"name": "AI and data leadership", "text": "VP, Head or Director of ..."}], "gates": [], "weights": {}, "limits": {}, "enabled": true, "created_at": "..."} +``` + +`prompts` is an ordered list of `{name, text}`; `name` is unique within the agent and non-empty, `text` may be empty. `POST` still accepts `intent` when `prompts` is absent and stores it as one prompt; `GET` no longer returns `intent`. + +Search JSON, in `POST /api/searches` and `/api/searches/try`: provider `platsbanken` takes `q`, `region` (a concept id, or empty for all of Sweden) and `pages`. `plugins.search` exports `PLATSBANKEN_REGIONS: dict[str, str]` (concept id to label); the Sources template receives it as `regions`, a list of `(value, label)`. + +## Work packages + +| WP | Branch | Model | Owns | +|---|---|---|---| +| 1 Platsbanken | `wp1-platsbanken` | Sonnet | `plugins/search.py`, `app/jobs/sources.py`, `tests/test_search.py`, `tests/test_sources.py` | +| 2 Job boards list | `wp2-jobboards-ui` | Sonnet | `app/templates/settings/sources.html`, `app/static/sources.js` | +| 3 Teamtailor | `wp3-teamtailor` | Sonnet | `plugins/ats.py`, `app/jobs/discover.py`, `tests/test_ats.py`, `tests/test_discover.py` | +| 4 Prompts backend | `wp4-prompts` | Opus | `app/models.py`, `app/storage/schema.py`, `app/storage/store.py`, `app/jobs/score.py`, `app/web/api.py`, `app/cli.py`, `config.example.yaml`, `tests/test_score.py`, `tests/test_storage.py`, `tests/test_web.py` | +| 5 Agents UI | `wp5-agents-ui` | Opus | `app/templates/settings/agents.html`, `app/static/agents.js`, `app/static/app.css` | + +**WP1.** `search_platsbanken` beside `search_jobindex` and `search_adzuna`, with paging, the completeness rule Adzuna uses (read as many as the stated total), `country` `SE`, `place` from the municipality, `remote` where the ad states it, `published_at`, description. `search_params` takes `region`. + +**WP2.** The Job boards section shows the list and a New button, as the Search agents page does: the form is a `