create-stellar-service 0.0.0-stage → 0.1.0

package/templates/python/Dockerfile

@@ -0,0 +1,27 @@
+# {{name}}: the FastAPI app and the Provider Kit gateway in one container. The app listens on 127.0.0.1:8000, inside
+# the container only, and the gateway on port 8787, in front of it.
+#
+#   docker build -t {{package}} .
+#   docker run -p 8787:8787 -v {{package}}-jobs:/data -e PAY_TO=G... -e PUBLIC_ORIGIN=https://your.domain {{package}}
+#
+# Paid jobs are kept in /data/jobs.sqlite: give /data a persistent volume. The image holds no Stellar secret key.
+# fly.toml deploys it on Fly.io: npm run launch does, or npm run deploy.
+
+FROM node:24-slim
+RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv && rm -rf /var/lib/apt/lists/*
+ENV NODE_ENV=production JOB_DB_PATH=/data/jobs.sqlite PATH=/opt/venv/bin:$PATH
+WORKDIR /app
+COPY requirements.txt ./
+RUN python3 -m venv /opt/venv && pip install --no-cache-dir -r requirements.txt
+COPY package.json package-lock.json ./
+{{vendor}}
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
+COPY app.py provider.config.json start.sh ./
+RUN mkdir -p /data && chown node:node /data
+VOLUME /data
+EXPOSE 8787
+HEALTHCHECK --interval=30s --timeout=5s CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 8787) + '/healthz').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+# A host's new volume may belong to root, as Fly.io's do: started as root, the container only gives /data to the node
+# user, then runs the service as node. Started as another user, it runs as that user.
+ENTRYPOINT ["sh", "-c", "if [ \"$(id -u)\" = 0 ]; then chown node:node /data 2>/dev/null || true; exec setpriv --reuid=node --regid=node --init-groups -- \"$@\"; fi; exec \"$@\"", "sh"]
+CMD ["sh", "start.sh"]

package/templates/python/app.py

@@ -0,0 +1,39 @@
+"""{{name}}: the service itself, a FastAPI app that knows nothing about payments.
+
+The Provider Kit gateway (provider.config.json) stands in front of it. It publishes the manifest, takes the USDC
+payment, queues jobs and keeps them for recovery, and POSTs only validated input here. Keep the models below in step
+with the schemas in provider.config.json: agents read those before they pay.
+
+`npm run dev` starts it next to the gateway: {{apiCommand}}
+"""
+
+import re
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+app = FastAPI(title={{nameJson}})
+
+
+class SummarizeIn(BaseModel):
+    text: str = Field(min_length=1, max_length=20000, description="The text to summarize")
+    sentences: int = Field(default=1, ge=1, le=5, description="How many sentences to keep")
+
+
+class SummarizeOut(BaseModel):
+    summary: str
+    sentences: int = Field(description="Sentences in the text")
+    words: int = Field(description="Words in the text")
+
+
+@app.post(
+    "/summarize",
+    summary="Summarize",
+    description="Returns the first sentences of an English text, with its sentence and word counts. Use it to shorten "
+    "text before passing it on. Accepts up to 20,000 characters; it does not paraphrase.",
+)
+def summarize(body: SummarizeIn) -> SummarizeOut:
+    # Your own work goes here, such as a model call. The gateway sends the job id in the Idempotency-Key header, so
+    # a job it runs again after a restart can be recognized.
+    parts = [part.strip() for part in re.split(r"(?<=[.!?])\s+", body.text) if part.strip()]
+    return SummarizeOut(summary=" ".join(parts[: body.sentences]), sentences=len(parts), words=len(body.text.split()))

package/templates/python/requirements.txt

@@ -0,0 +1,2 @@
+fastapi==0.115.12
+uvicorn==0.34.2

package/templates/python/start.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Starts the FastAPI app and the gateway in front of it. When either one stops, so does the other, and the container
+# exits for its host to restart. A stop signal reaches both: the gateway finishes the requests in flight.
+
+uvicorn app:app --host 127.0.0.1 --port 8000 &
+api=$!
+node node_modules/@stellar-agent-services/provider-kit/dist/cli/index.js serve --config provider.config.json &
+gateway=$!
+
+asked=0
+trap 'asked=1; kill -TERM "$api" "$gateway" 2>/dev/null' TERM INT
+while kill -0 "$api" 2>/dev/null && kill -0 "$gateway" 2>/dev/null; do sleep 1; done
+kill -TERM "$api" "$gateway" 2>/dev/null
+wait
+# 0 when asked to stop; 1 when one of them stopped by itself.
+[ "$asked" = 1 ]

package/templates/typescript/Dockerfile

@@ -0,0 +1,31 @@
+# {{name}}: the service and its job database, on any host that runs a container.
+#
+#   docker build -t {{package}} .
+#   docker run -p 8787:8787 -v {{package}}-jobs:/data -e PAY_TO=G... -e PUBLIC_ORIGIN=https://your.domain {{package}}
+#
+# Paid jobs are kept in /data/jobs.sqlite: give /data a persistent volume. The image holds no Stellar secret key.
+# fly.toml deploys it on Fly.io: npm run launch does, or npm run deploy.
+
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json tsconfig.json ./
+{{vendor}}
+RUN npm ci --ignore-scripts
+COPY src ./src
+RUN npx tsc
+
+FROM node:24-slim
+ENV NODE_ENV=production JOB_DB_PATH=/data/jobs.sqlite
+WORKDIR /app
+COPY package.json package-lock.json ./
+{{vendor}}
+RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
+COPY --from=build /app/dist ./dist
+RUN mkdir -p /data && chown node:node /data
+VOLUME /data
+EXPOSE 8787
+HEALTHCHECK --interval=30s --timeout=5s CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 8787) + '/healthz').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
+# A host's new volume may belong to root, as Fly.io's do: started as root, the container only gives /data to the node
+# user, then runs the service as node. Started as another user, it runs as that user.
+ENTRYPOINT ["sh", "-c", "if [ \"$(id -u)\" = 0 ]; then chown node:node /data 2>/dev/null || true; exec setpriv --reuid=node --regid=node --init-groups -- \"$@\"; fi; exec \"$@\"", "sh"]
+CMD ["node", "--disable-warning=ExperimentalWarning", "dist/server.js"]

package/templates/typescript/src/server.ts

@@ -0,0 +1,57 @@
+// {{name}}: a paid service on Stellar, built with the Provider Kit (Provider Standard v1).
+//
+// Settings come from .env: public values, and on mainnet the facilitator's API key. This service never needs a Stellar
+// secret key. Paid jobs are kept in SQLite (JOB_DB_PATH), so they survive a restart, and a client that lost its
+// response can still collect the result. Add services in src/services/ and list them below. `npm run launch` starts
+// this file with PUBLIC_ORIGIN set to the public address, to read the manifest it will serve there.
+
+import { createProvider, httpFacilitator, listen, sqliteStore, type ProviderConfig } from "@stellar-agent-services/provider-kit";
+import { summarize } from "./services/summarize.js";
+
+const port = Number(process.env["PORT"] ?? "8787");
+const origin = process.env["PUBLIC_ORIGIN"] ?? `http://localhost:${port}`;
+const dev = origin.startsWith("http://localhost");
+// stellar:testnet takes test money; stellar:pubnet is mainnet, real USDC.
+const network = (process.env["STELLAR_NETWORK"] ?? "stellar:testnet") as ProviderConfig["network"];
+const payTo = process.env["PAY_TO"];
+if (!payTo) throw new Error(`PAY_TO is empty: npm run launch sets up your own wallet${network === "stellar:testnet" ? ", and npm run dev makes a throwaway testnet account meanwhile" : ""}.`);
+const agentId = process.env["AGENT_ID"];
+const rpcUrl = process.env["SOROBAN_RPC_URL"];
+
+// The facilitator verifies and settles payments: x402.org's on testnet, OpenZeppelin's on mainnet, which wants an API
+// key. FACILITATOR_AUTH is sent as the Authorization header: "Bearer <key>".
+const facilitatorUrl = process.env["FACILITATOR_URL"] ?? (network === "stellar:pubnet" ? "https://channels.openzeppelin.com/x402" : "https://x402.org/facilitator");
+const facilitatorAuth = process.env["FACILITATOR_AUTH"];
+if (network === "stellar:pubnet" && !facilitatorAuth && !process.env["FACILITATOR_URL"]) {
+  throw new Error('FACILITATOR_AUTH is empty: get an API key at https://channels.openzeppelin.com/gen, and set FACILITATOR_AUTH="Bearer <key>" in .env.');
+}
+
+const provider = createProvider({
+  baseUrl: origin,
+  dev,
+  network,
+  payTo,
+  facilitator: httpFacilitator(facilitatorUrl, { dev, ...(facilitatorAuth ? { headers: { Authorization: facilitatorAuth } } : {}) }),
+  // Search matches only this name and description: use the words buyers type.
+  provider: {
+    name: {{nameJson}},
+    description: {{descriptionJson}},
+    dataUse: { storesInputs: false, trainsOnInputs: false },
+    ...(agentId ? { agentId: Number(agentId) } : {}),
+  },
+  services: [summarize],
+  store: sqliteStore(process.env["JOB_DB_PATH"] ?? "./jobs.sqlite"),
+  // Decides payment_uncertain jobs from the chain. Testnet defaults to the public RPC; mainnet needs one.
+  ...(rpcUrl ? { rpc: rpcUrl } : {}),
+});
+
+// Fails fast if the facilitator can't settle this network, and resumes jobs a restart left behind.
+await provider.ready();
+const server = await listen(provider, { port });
+console.log(`Listening on ${origin}`);
+console.log(`Manifest: ${provider.manifestUrl}`);
+console.log(`payTo:    ${payTo}`);
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.once(signal, () => void server.close().then(() => process.exit(0)));
+}

package/templates/typescript/src/services/summarize.ts

@@ -0,0 +1,47 @@
+// summarize: {{price}} USDC, charged only if it succeeds. Replace the handler with your own work, such as a model call,
+// and keep the description, schemas and example in step with it: agents read them before they pay.
+
+import { defineService } from "@stellar-agent-services/provider-kit";
+
+type Input = { text: string; sentences?: number };
+
+export const summarize = defineService({
+  name: "summarize",
+  title: "Summarize",
+  description:
+    "Returns the first sentences of an English text, with its sentence and word counts. Use it to shorten text before passing it on. Accepts up to 20,000 characters; it does not paraphrase.",
+  price: "{{price}}",
+  charge: "on-success",
+  expectedDurationSeconds: 1,
+  inputSchema: {
+    type: "object",
+    required: ["text"],
+    properties: {
+      text: { type: "string", minLength: 1, maxLength: 20000, description: "The text to summarize" },
+      sentences: { type: "integer", minimum: 1, maximum: 5, default: 1, description: "How many sentences to keep" },
+    },
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    required: ["summary", "sentences", "words"],
+    properties: {
+      summary: { type: "string" },
+      sentences: { type: "integer", description: "Sentences in the text" },
+      words: { type: "integer", description: "Words in the text" },
+    },
+  },
+  examples: [
+    {
+      input: { text: "Stellar settles in seconds. Fees are tiny.", sentences: 1 },
+      output: { summary: "Stellar settles in seconds.", sentences: 2, words: 7 },
+    },
+  ],
+  handler: ({ text, sentences = 1 }: Input) => {
+    const parts = text
+      .split(/(?<=[.!?])\s+/)
+      .map((part) => part.trim())
+      .filter(Boolean);
+    return { summary: parts.slice(0, sentences).join(" "), sentences: parts.length, words: text.split(/\s+/).filter(Boolean).length };
+  },
+});

package/templates/typescript/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}