add-python-microservice

name	add-python-microservice
description	TRIGGER when user asks to create a microservice that calls Python, runs ML inference, or uses Python libraries (PyTorch, pandas, sentence-transformers, numpy) for its core compute.

CRITICAL: Read .claude/rules/python.txt before proceeding.

CRITICAL: Do NOT explore or analyze other microservices unless explicitly instructed to do so.

Workflow

This skill works in two modes:

• New microservice: starts at Step 1, runs the standard add-microservice scaffold first.
• Extend existing microservice: skips Step 1; the target package already exists and may have business logic. Every subsequent step is additive (it appends, never overwrites).

Copy this checklist and track your progress:

Adding Python support to a microservice:
- [ ] Step 1: Run add-microservice (skip when extending an existing service)
- [ ] Step 2: Add Python source files
- [ ] Step 3: Add python.go
- [ ] Step 4: Extend the Service fields
- [ ] Step 5: Add MaxWorkers config
- [ ] Step 6: Wire OnStartup and OnShutdown
- [ ] Step 7: Housekeeping

Step 1: Run add-microservice

Skip this step when extending an existing microservice.

Otherwise, run the add-microservice skill, skipping its housekeeping step (housekeeping runs once at the end of this skill instead). When it finishes, return here. The remaining steps assume myservice/ is the microservice directory.

Step 2: Add Python Source Files

Refuse to overwrite if either file already exists. Copy the template files to the microservice's root:

test -e myservice/service.py        || cp .claude/skills/python/add-python-microservice/service.py myservice/service.py
test -e myservice/requirements.txt  || cp .claude/skills/python/add-python-microservice/requirements.txt myservice/requirements.txt

Step 3: Add python.go

Refuse to overwrite if the file already exists:

test -e myservice/python.go || cp .claude/skills/python/add-python-microservice/python.go myservice/python.go

Change package myservice to match the microservice's package name. Leave the rest unchanged.

Step 4: Extend the Service Fields

In service.go, append the venv field to the existing Service struct, preserving any fields already there:

type Service struct {
    *Intermediate // IMPORTANT: Do not remove

    // ...existing fields...
    venv *pyvenv.Venv
}

Add these imports to service.go if they're not already there:

import (
    // ...
    "github.com/microbus-io/fabric/connector"
    "github.com/microbus-io/pyvenv"
)

Step 5: Add MaxWorkers Config

Run add-config:

• Name: MaxWorkers
• Type: int
• Validation: int [1,]
• Default: match the workload (e.g. 1 for LLM inference, 4 for I/O, 8 for parallel numpy/pandas)
• Description: MaxWorkers caps how many calls into the Python venv may run concurrently.

Step 6: Wire OnStartup and OnShutdown

Add the Python lifecycle wiring to the existing OnStartup and OnShutdown bodies. Do not delete any existing code; append the new lines around it.

In OnStartup, add this block (anywhere in the body, but conventionally at the end so any earlier setup is in place before the venv goroutine launches):

sources, err := readPythonSources()
if err != nil {
    return errors.Trace(err)
}
svc.venv, err = pyvenv.New(pyvenv.Config{
    Sources:          sources,
    Requirements:     parseRequirements(pythonRequirements),
    MaxWorkers:       svc.MaxWorkers(),
    Logger:           svc,
    LivenessCallback: svc.onVenvLiveness,
})
if err != nil {
    return errors.Trace(err)
}
// Start the venv in the background. Auto-start is gated on deployment; in TESTING the
// venv is left dormant (parallels how tickers don't run in TESTING).
if svc.Deployment() != connector.TESTING {
    // Tests opt-in by calling svc.StartPyVenv(ctx)
    svc.Go(ctx, svc.venv.Start)
}

In OnShutdown, add this block (conventionally at the start, so the venv is released before any downstream resources the service shuts down later):

if svc.venv != nil {
    err := svc.venv.Close(ctx)
    if err != nil {
        svc.LogError(ctx, "Closing python venv failed", "error", err)
    }
}

Step 7: Housekeeping

Follow the housekeeping skill.