Add a Task

This skill adds curated rows to the tasks table so task pages, paper tagging, and benchmark leaderboards render correctly. Prefer small idempotent migrations plus applying the same change to the live database.

Image storage: seed PNG → /tmp/paperswithcode_entity_image_seeds/tasks/<slug>.png → import_entity_image.py → SQL bytes served at /api/v1/tasks/<slug>/image. Do not put task heroes in frontend/public/ (that folder is for browser assets only: favicons, og-image.png, logos).

When the user says "similarly add X" (often with just a name and area), run the full workflow below without re-asking — same area, parent, keywords, thumbnail, keyword backfill, and deploy steps as the prior task in the conversation unless they specify otherwise.

When the user asks "should we add X?", briefly judge whether the topic is distinct enough from an existing task slug (e.g. object-detection vs 3d-object-detection, image-restoration vs image-super-resolution). If yes, add it; if it is only a synonym or a narrow variant of an existing task, say so and suggest updating keywords on the existing row instead.

End-to-End Checklist

For a typical new top-level task:

1. Confirm the task does not already exist (slug, name, keywords).
2. Pick the right area and optional parent (subtask vs top-level).
3. Write metadata + migration SQL (or ensure_task Python script).
4. Add hero image: save seed PNG under /tmp/paperswithcode_entity_image_seeds/tasks/<slug>.png, then import into SQL (see Thumbnail).
5. Apply migration to the live DB.
6. Run keyword backfill so existing papers get tagged (see Keyword linking).
7. Verify API + report production URL.

Skip keyword backfill only when the user explicitly asks for the task row alone.

8. Recommend benchmarks the user should add next (do not auto-add unless they ask — use add-benchmark for ingestion).

Core Rules

Tasks are first-class taxonomy nodes. Each task gets its own page at /tasks/<slug> with description, linked benchmarks, and paper counts.

• Top-level tasks have parent_id = NULL and level = 0.
• Subtasks are child rows with parent_id pointing at the parent task and level = parent.level + 1. Each subtask has its own page, benchmarks, and evaluations. Example: language-modeling (level 0) → world-knowledge, math, coding (level 1).
• area_id groups tasks for area browse pages. It does not drive the "Sister Tasks" sidebar — that uses the explicit task_sister_tasks table when curated.
• keywords: comma-separated phrases used by the keyword matcher to tag papers. Include exact name, hyphenated variants, common abbreviations, and related phrasing researchers use in titles/abstracts. Follow casing rules in docs/keyword-matching.md (lowercase for phrases, preserve caps for acronyms like ASR, MOT, VLM).
• Descriptions: one concise paragraph — what the task is, typical inputs/outputs, and why it matters. Link related on-site tasks with relative markdown, e.g. [Object Detection](/tasks/object-detection), [Image Segmentation](/tasks/image-segmentation). Never hard-code paperswithcode.co or localhost inside markdown fields.
• Images: curated self-hosted heroes are stored in SQL (image_data / image_mime_type) and served at /api/v1/tasks/{slug}/image. Do not add runtime assets under frontend/public/images/. Legacy rows may still have external image_url values; new tasks should import a local PNG into the DB (see Thumbnail).

Workflow

1. Understand the requested task

• Record name, target area (Vision, Language, Audio, Video, General, Other), whether it is a subtask of an existing task, and any image the user attached.
• Pick a stable slug: lowercase words joined by hyphens (tabular-learning, object-tracking, image-super-resolution). Prefer community naming over internal jargon.
• Search for an existing task by name, slug, and keywords before creating a new row.
• Query sibling tasks in the same area or under the same parent to calibrate description tone and keyword coverage.

Live DB areas:

Area lookup in SQL:

(SELECT id FROM areas WHERE name = 'Vision' LIMIT 1)
-- Language, Audio, Video, General, Other — same pattern

2. Choose metadata

• name: display title (e.g. Tabular Learning, Object Tracking, Image super-resolution).
• description: one paragraph; link related tasks/methods on-site when helpful.
• keywords: broad coverage for paper tagging — task name, aliases, abbreviations, compound phrases (multi-object tracking, MOT, visual object tracking).
• area_id: resolve by area name (see table above).
• parent_id / level: set only for subtasks. Look up parent by slug; level = parent.level + 1.
• image_url: leave NULL for new self-hosted images — the API resolves /api/v1/tasks/<slug>/image once image_mime_type is set. Use an external URL only when you cannot self-host.
• image_credit: attribution as markdown link or plain URL, e.g. [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) or a source paper link [Paper title](/paper/2005.08100).
• useful_leaderboards: optional comma-separated external leaderboard URLs (HF Spaces, community leaderboards) when the user provides them or you find a canonical one for the domain.

3. Thumbnail

Task hero images are DB-backed. Save a seed PNG, import it, then verify the API image endpoint.

If the user provides an image, copy it to:

/tmp/paperswithcode_entity_image_seeds/tasks/<slug>.png

Otherwise, find a suitable diagram:

1. Check whether a related task, survey paper, or benchmark homepage has a clear task illustration.
2. For arXiv-backed domains, download https://arxiv.org/pdf/<arxiv_id>.pdf and extract a figure with PyMuPDF (fitz) — same approach as add-method: locate figure captions, crop the main task diagram (not tables-only), render at 3× zoom.
3. Save to /tmp/paperswithcode_entity_image_seeds/tasks/<slug>.png.
4. Set image_credit to the source.

After the task row exists, import the PNG into SQL:

uv run --env-file backend/keys.env python backend/database/import_entity_image.py \
    tasks <slug> /tmp/paperswithcode_entity_image_seeds/tasks/<slug>.png

Prefer self-hosted DB images for new tasks. External hotlinks are acceptable only when licensing/hosting makes local copy impractical and the user agrees.

No frontend rebuild is needed for entity images — they are served from the backend API.

4. Create and apply migration

Add backend/database/migrations/add_<slug>_task.sql using ON CONFLICT (slug) DO UPDATE.

Top-level task example:

INSERT INTO tasks (
    name, slug, description, keywords, area_id, level, parent_id,
    image_url, image_credit, useful_leaderboards
)
VALUES (
    '<Name>',
    '<slug>',
    '<description with [Related Task](/tasks/related)>',
    '<keywords>',
    (SELECT id FROM areas WHERE name = 'Vision' LIMIT 1),
    0,
    NULL,
    NULL,
    '[<credit label>](<url>)',
    NULL  -- or comma-separated external leaderboard URLs
)
ON CONFLICT (slug) DO UPDATE SET
    name = EXCLUDED.name,
    description = EXCLUDED.description,
    keywords = EXCLUDED.keywords,
    area_id = EXCLUDED.area_id,
    level = EXCLUDED.level,
    parent_id = EXCLUDED.parent_id,
    image_url = EXCLUDED.image_url,
    image_credit = EXCLUDED.image_credit,
    useful_leaderboards = EXCLUDED.useful_leaderboards,
    updated_at = CURRENT_TIMESTAMP;

Subtask example — resolve parent first:

INSERT INTO tasks (
    name, slug, description, keywords, area_id, level, parent_id
)
VALUES (
    '<Subtask Name>',
    '<subtask-slug>',
    '<description>',
    '<keywords>',
    (SELECT area_id FROM tasks WHERE slug = '<parent-slug>' LIMIT 1),
    (SELECT level + 1 FROM tasks WHERE slug = '<parent-slug>' LIMIT 1),
    (SELECT id FROM tasks WHERE slug = '<parent-slug>' LIMIT 1)
)
ON CONFLICT (slug) DO UPDATE SET
    name = EXCLUDED.name,
    description = EXCLUDED.description,
    keywords = EXCLUDED.keywords,
    area_id = EXCLUDED.area_id,
    level = EXCLUDED.level,
    parent_id = EXCLUDED.parent_id,
    updated_at = CURRENT_TIMESTAMP;

Alternatively, use the idempotent Python pattern from existing setup scripts (TaskService.create_task + update-on-exists), e.g. backend/database/tasks_setup/add_tabular_learning_task.py.

Apply to the live DB:

uv run --env-file backend/keys.env python3 - <<'PY'
from pathlib import Path
from sqlalchemy import text
from backend.database.connection import db_manager

sql = Path("backend/database/migrations/add_<slug>_task.sql").read_text()
with db_manager.engine.begin() as conn:
    conn.execute(text(sql))
PY

5. Keyword linking

After the task row exists with keywords, tag existing local papers whose titles/abstracts match:

# Add-only (safe default): inserts new paper_tasks rows, never removes
uv run --env-file backend/keys.env \
    backend/database/tasks_setup/link_papers_by_task_keywords.py

# Rebuild auto tags for the whole corpus (only when user asks)
uv run --env-file backend/keys.env \
    backend/database/tasks_setup/link_papers_by_task_keywords.py --rebuild

This inserts paper_tasks rows with source = 'auto'. Run this by default when adding a task unless the user opts out.

6. Optional: sister tasks

When the user wants related tasks shown in the sidebar, insert into task_sister_tasks:

INSERT INTO task_sister_tasks (task_id, sister_task_id, display_order)
SELECT t.id, s.id, v.ord
FROM tasks t
CROSS JOIN (VALUES ('<sister-slug>', 0), ('<other-sister-slug>', 1)) AS v(slug, ord)
JOIN tasks s ON s.slug = v.slug
WHERE t.slug = '<slug>'
ON CONFLICT DO NOTHING;

Sister links are directed — configuring A → B does not imply B → A.

7. Recommend benchmarks (required in report)

Do not silently create benchmark rows unless the user asked. Instead, research and return a curated recommendation list.

To build recommendations:

1. Query existing datasets already linked to similar tasks:

SELECT t.slug AS task_slug, d.name, d.slug, m.name AS metric
FROM task_datasets td
JOIN tasks t ON t.id = td.task_id
JOIN datasets d ON d.id = td.dataset_id
LEFT JOIN task_dataset_metrics tdm ON tdm.task_id = td.task_id AND tdm.dataset_id = td.dataset_id
LEFT JOIN metrics m ON m.id = tdm.metric_id
WHERE t.slug IN ('<similar-task-1>', '<similar-task-2>')
ORDER BY t.slug, d.name;

2. Search datasets by name/slug for benchmarks commonly associated with the new task but not yet linked.
3. Use domain knowledge — pick community-standard benchmarks researchers expect on a PapersWithCode task page (e.g. COCO/LVIS for object detection, LibriSpeech for ASR, GLUE/SuperGLUE for classic NLP).
4. For each recommendation, note:
   • Benchmark name and whether it already exists in datasets
   • Suggested metric (e.g. mAP, WER, Accuracy)
   • Whether it is already linked to a sibling task (reuse vs new add-benchmark work)
   • Source paper if known (for add-benchmark provenance)

When the user wants benchmarks ingested, switch to the add-benchmark skill.

Database Access

Run Python and project CLIs from the repo root:

uv run --env-file backend/keys.env python3 ...

Keep writes scoped to the requested task. Do not rewrite unrelated task metadata or paper tags.

Verification

Before reporting done:

1. Task row:

SELECT t.id, t.slug, t.name, t.area_id, a.name AS area,
       t.parent_id, t.level, t.image_url, t.image_mime_type
FROM tasks t
LEFT JOIN areas a ON a.id = t.area_id
WHERE t.slug = '<slug>';

2. Keyword-tagged paper count:

SELECT COUNT(*) FROM paper_tasks pt
JOIN tasks t ON t.id = pt.task_id
WHERE t.slug = '<slug>';

3. Task API (expect "image_url": "/api/v1/tasks/<slug>/image" when DB image imported):

curl -fsS "http://localhost:8000/api/v1/tasks/<slug>" | uv run python3 -m json.tool
curl -fsS -o /dev/null -w "%{http_code}\n" "http://localhost:8000/api/v1/tasks/<slug>/image"

4. Task datasets (may be empty until benchmarks are added):

curl -fsS "http://localhost:8000/api/v1/tasks/<slug>/datasets" | uv run python3 -m json.tool

If the API is stale, verify the database row directly and report the stale API response. Do not start or restart deployed services during data curation.

Reporting Back

Always include:

• Production task URL: https://paperswithcode.co/tasks/<slug>
• Hierarchy: top-level or subtask of <parent-slug> (with level)
• Area assigned
• Thumbnail: confirm /api/v1/tasks/<slug>/image returns HTTP 200 after import
• Keyword linking summary: how many papers tagged after backfill
• Recommended benchmarks — numbered list with:
  • Benchmark name
  • Suggested metric
  • Whether it already exists in DB / is linked to a sibling task
  • One-line rationale
  • Note: "Run add-benchmark to ingest these" unless the user already asked to add them

Example recommendation block:

Recommended benchmarks to add next:
1. COCO val2017 (metric: mAP) — already in DB, linked to object-detection; link to this task via add-benchmark
2. LVIS (metric: mAP) — standard open-vocabulary detection benchmark
3. Objects365 — widely used in recent detection papers

Reference: recent task additions