---

name: local-development description: "Local Marqo repository development, service operation, testing, Docker/Vespa/Triton prerequisites, Maven custom searcher build guidance, and contributor constraints." disable-model-invocation: true metadata: disco-role: operating repo: marqo sub-skill-id: local-development license: Apache 2.0

local-development

Use this sub-skill when the task is about preparing a Marqo development environment, choosing local tests, planning service startup, diagnosing local Docker/Vespa/Triton/Redis/Zookeeper problems, building the Vespa custom searcher, or applying repository contribution rules.

Do not use this sub-skill for API payload semantics, index/search/model internals, or user-facing request examples beyond service/test setup:

• Public route behavior, document/index/typeahead payloads → documents-and-api.
• Index schemas, Vespa query generation, field-type semantics → index-and-vespa.
• Search/ranking/filter/score semantics → search-and-ranking.
• Inference schemas, model registry, model-management payloads → inference-and-models.

Required operating pattern

1. Start from the relevant bundled reference:
   • Local services for service topology, environment variables, compose profiles, Vespa/API/Triton/MMC/MIOC plans, ports, and Java/Maven custom searcher build steps.
   • Testing for safe unit/integration/API-test command selection, working directories, PYTHONPATH, and service prerequisites.
   • Contributor guidance for maintainer rules, imports, exceptions, semi-structured changes, and test style.
   • Troubleshooting for failure-mode triage.
2. Prefer safe planning before mutation. The bundled scripts print plans by default:
   • scripts/print_service_commands.py prints service/build/test command plans without running them.
   • scripts/select_tests.py maps changed files to a minimal test plan without running tests unless --run is explicitly passed.
3. Before running any repository command, activate the intended Python environment and load the repository .env variables when present. Use Python 3.11 for Marqo services.
4. For Marqo unit and integration tests, run from the Marqo component root with PYTHONPATH=./src. For API tests, run a Marqo API process first and terminate it after the test session.
5. If HybridSearcher.java or Vespa custom searcher code changes, build the custom searcher with Maven and redeploy the Vespa application package before validating behavior against Vespa.
6. Treat Docker/Vespa/API tests as service-mutating: they can create/delete indexes, start/stop containers, download images/models, and change local ports. Ask for explicit approval when the task has not already authorized service changes.

Quick safe helpers

From this sub-skill directory, print commands only:

python scripts/print_service_commands.py --plan all
python scripts/print_service_commands.py --plan local-api
python scripts/select_tests.py components/marqo/src/marqo/core/semi_structured_vespa_index/semi_structured_vespa_index.py

Only run selected safe unit tests when explicitly requested:

python scripts/select_tests.py --run components/marqo/src/marqo/core/semi_structured_vespa_index/semi_structured_vespa_index.py

The scripts never start or stop containers and never run service-backed tests.