Skip to content

feat: refine template manifesto with use case tags#775

Open
DaveHanns wants to merge 3 commits into
masterfrom
feat/refine-template-manifesto
Open

feat: refine template manifesto with use case tags#775
DaveHanns wants to merge 3 commits into
masterfrom
feat/refine-template-manifesto

Conversation

@DaveHanns
Copy link
Copy Markdown
Contributor

Summary

Refines the useCases tags across Actor templates so the Console wizard's "use case + language" filter produces a meaningful split, polishes a handful of template descriptions, and adds in-place documentation for what each use case represents.

Changes

useCases tag refinements

  • python/ts/js-empty: [WEB_SCRAPING][STARTER] (empties are topic-agnostic, not scrapers).
  • python/ts/js-standby (×3): added INTEGRATION to [STARTER] (Standby actors serve HTTP, callable by outside systems).
  • python-mcp-proxy, python-mcp-empty, ts-mcp-proxy, ts-mcp-empty (×4): added INTEGRATION to [AI] (callable by AI clients via the MCP protocol).
  • ts-playwright-test-runner: [WEB_SCRAPING][AUTOMATION] (it's a test runner — automation, not scraping).
  • python-playwright / python-selenium: added AUTOMATION to [WEB_SCRAPING] (pure browser tooling without a scraping framework — repurposable for automation).
  • cli-start: filled in the previously missing useCases with [STARTER, INTEGRATION] (the Dockerfile sets up ubi to install third-party binaries — Actorization is integration).

Description polish

  • Rewritten descriptions for 9 templates (python-crawlee-beautifulsoup, python-empty, python-standby, python-crawlee-parsel, python-crawlee-playwright, python-crawlee-playwright-camoufox, python-smolagents, js-langchain, cli-start) — clearer, more direct phrasing, and consistent grammar (e.g. "Start from a given start URLs" → "Start from a URL").

Documentation

  • Added _useCaseDescriptions field at the manifest top-level — a self-contained reference for what each tag represents. Canonical enum + JSDoc lives in apify-core (TEMPLATE_USE_CASES in src/packages/consts/src/templates.ts).

Tagging principles applied

The tagging principle is: tag for what the template IS (its primary framing/purpose), not what it COULD become. Concretely:

  • Empty scaffolds carry only STARTER (no inherent topic).
  • STARTER is for entry-level / first-Actor scaffolds. Skeletons explicitly aimed at experienced devs don't qualify.
  • Pure browser tooling (raw Playwright / Selenium, no Crawlee wrapping) can earn AUTOMATION in addition to WEB_SCRAPING — the underlying tool is genuinely repurposable.
  • Crawlee variants stay WEB_SCRAPING only — Crawlee's crawler-specific abstractions (request queue, *Crawler classes) orient the project toward scraping, even when paired with Playwright/Puppeteer.
  • AI agents stay AI-only, even when they crawl as part of their workflow. Calling Apify Actors as tools or fetching web data is a means; the AI framework demo is the product.
  • INTEGRATION is reserved for templates that meaningfully bridge Apify with external systems: Standby HTTP servers, MCP servers callable by AI clients, or third-party-tool wrappers (cli-start). Not "any Actor that has an API surface" — that would be everything.

Coverage after changes

Use case → templates

Use case Count
WEB_SCRAPING 21
STARTER 17
AI 13
INTEGRATION 8
AUTOMATION 4

Use case × language

Use case JavaScript Python TypeScript Total
WEB_SCRAPING 6 9 6 21
STARTER 5 7 5 17
AI 2 7 4 13
INTEGRATION 2 3 3 8
AUTOMATION 1 2 1 4

Open for refinement

This pass focused on obvious mistags and missing tags. Further iteration welcome — especially around:

  • JS / TS AUTOMATION = 1 eachjs-cypress and ts-playwright-test-runner respectively. Both are test runners. No general-purpose JS/TS browser-automation template exists; an equivalent of python-playwright/python-selenium for each would fill the gap.
  • JS INTEGRATION = 2js-standby + cli-start. No JS MCP template exists; adding one would mirror the Python/TS coverage.
  • Individual template judgement calls — tagging is partly subjective. Happy to iterate on any specific template.

No changes to template content or behavior — only metadata in manifest.json.

@DaveHanns DaveHanns self-assigned this May 19, 2026
@DaveHanns DaveHanns added the adhoc Ad-hoc unplanned task added during the sprint. label May 19, 2026
@github-actions github-actions Bot added this to the 141st sprint - DX team milestone May 19, 2026
@github-actions github-actions Bot added the t-dx Issues owned by the DX team. label May 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

adhoc Ad-hoc unplanned task added during the sprint. t-dx Issues owned by the DX team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants