# SwishrJobs — agent contract

This file is the authoritative list of what swishrjobs.com publishes for agents.
It is regenerated from the running code, so it matches what the service does.

## Published surfaces

| Surface | Path | Status |
|---|---|---|
| A2A agent card (protocol 1.0) | /.well-known/agent-card.json | published |
| OpenAPI document | /openapi.json | published |
| Capability list | /v1/capabilities | published |
| Job preflight and quote | POST /v1/jobs | published |
| Job authorization and run | POST /v1/jobs/{id}/authorize | published |
| Job status | GET /v1/jobs/{id} | published (needs the job access token) |
| Job list | GET /v1/jobs | published (scoped to the job access token) |
| MCP tools (stdio) | swishrjobs serve --mcp | published |
| A2A JSON-RPC | /a2a | published |
| ARD manifest | /.well-known/ard.json | published |
| AI Catalog | /.well-known/ai-catalog.json | published |
| llms.txt | /llms.txt | published |

## Capabilities

| id | title | inputs | status |
|---|---|---|---|
| boundary-value-generation | Boundary value generator module with pytest tests | module_name, function_name, template | available |
| csv-json-transformation | CSV to JSON transform script with pytest tests | module_name, function_name, template | available |
| data-validation-module | Data validation module with pytest tests | module_name, function_name, template | available |
| dataset-quality-report | Dataset quality report module with pytest tests | module_name, function_name, template | available |
| duplicate-group-report | Duplicate group report module with pytest tests | module_name, function_name, template | available |
| edge-case-check | Edge-case check module with pytest tests | module_name, function_name, template | available |
| field-mapping | Field mapping and renaming module with pytest tests | module_name, function_name, template | available |
| json-csv-conversion | JSON to CSV transform module with pytest tests | module_name, function_name, template | available |
| json-schema-inference | JSON Schema inference module with pytest tests | module_name, function_name, template | available |
| key-normalisation | Object key normalisation module with pytest tests | module_name, function_name, template | available |
| malformed-record-detection | Malformed-record detection module with pytest tests | module_name, function_name, template | available |
| markdown-table-rendering | Markdown table renderer with pytest tests | module_name, function_name, template | available |
| metadata-extraction | Metadata extraction module with pytest tests | module_name, function_name, template | available |
| nested-flattening | Nested-object flattening module with pytest tests | module_name, function_name, template | available |
| python-multifile-package | Multi-file Python package with tests and README | module_name, function_name, template | available |
| python-utility-module | Python utility module with pytest tests | module_name, function_name, template | available |
| readme-generation | README generator module with pytest tests | module_name, function_name, template | available |
| record-deduplication | Record deduplication module with pytest tests | module_name, function_name, template | available |
| regex-from-examples | Regex builder module with pytest tests | module_name, function_name, template | available |
| regression-suite-generation | Regression suite generator with pytest tests | module_name, function_name, template | available |
| text-parser-module | Text parsing module with pytest tests | module_name, function_name, template | available |
| webhook-payload-validation | Webhook payload validation module with pytest tests | module_name, function_name, template | available |
| xml-json-conversion | XML to JSON conversion module with pytest tests | module_name, function_name, template | available |

## Choosing a capability

Each capability below states the requests it answers and, just as importantly,
what it is not for. Match your task against the summary and the example requests
before submitting; a request outside a capability's registered template is
rejected rather than approximated.

### boundary-value-generation

Produce a standard-library Python module that produces boundary values for an integer range, plus pytest tests.

- Use when: Choose this when you need the boundary and just-outside values of an inclusive integer range, with tests.
- Not for: Do not choose this for non-integer ranges, random data generation, or property-based testing frameworks.
- Example requests:
  - Write a Python module that produces the boundary and just-outside values for an integer range, with tests.
  - I need boundary values for an inclusive integer range for test data.
  - Generate a boundary-value module and prove it with pytest.

### csv-json-transformation

Produce a standard-library Python module that transforms CSV text into a JSON array of objects, plus pytest tests. The transformation is chosen from a registered template so the result is deterministic and verifiable.

- Use when: Choose this when you need a tested, standard-library function that parses CSV text into a JSON array of objects, one per row.
- Not for: Do not choose this for per-column type coercion or bespoke rules, or if you need the file converted for you rather than a module that does it: this delivers code, not converted data.
- Example requests:
  - Give me a Python module that turns CSV text into a JSON array of objects, with tests.
  - I have CSV and need JSON objects, one per row, produced by a tested function.
  - Convert CSV to JSON and prove it with a pytest suite.

### data-validation-module

Produce a standard-library Python module that validates a record and returns structured errors, plus pytest tests. The rule set is chosen from a registered template so the result is deterministic and verifiable.

- Use when: Choose this when a record must be checked against a registered rule set and the result is a list of human-readable errors, with tests.
- Not for: Do not choose this for rules outside the registered template, or when you need a schema-validation library rather than a self-contained module.
- Example requests:
  - Write a Python module that validates a record against a fixed rule set and returns a list of error strings.
  - I need a validation function that returns an empty list for valid input, with tests.
  - Generate a data-validation module and its pytest suite.

### dataset-quality-report

Produce a standard-library Python module that computes a quality report for an array of records, plus pytest tests.

- Use when: Choose this when you need a computed quality summary of a record array: counts, presence, nulls, completeness ratio, exact duplicates.
- Not for: Do not choose this for statistical or semantic quality (outliers, drift, schema conformance beyond the fixed checks).
- Example requests:
  - Write a Python module that reports record count, per-field presence and duplicate count for a dataset, with tests.
  - I need a data-quality summary: null counts, completeness ratio, exact duplicates.
  - Generate a dataset-quality report module and test it.

### duplicate-group-report

Produce a standard-library Python module that groups records sharing a key field, plus pytest tests.

- Use when: Choose this when you need each repeated key value reported with its count and the positions of its members.
- Not for: Do not choose this to remove duplicates (use record-deduplication) or to match near-duplicates.
- Example requests:
  - Write a Python module that groups records by a key field and reports duplicated values, with tests.
  - I need to know which key values occur more than once, with counts and positions.
  - Generate a duplicate-group report module and prove it with pytest.

### edge-case-check

Produce a standard-library Python module that reports boundary conditions for a text value, plus pytest tests.

- Use when: Choose this when a text value must be classified against a fixed set of boundary conditions, one boolean each.
- Not for: Do not choose this for validation with error messages (use data-validation-module) or for conditions outside the fixed set.
- Example requests:
  - Write a Python module that reports which boundary conditions a text value satisfies, with tests.
  - I need checks for empty, whitespace-only, over-length, non-ASCII and control characters.
  - Generate an edge-case check module and prove it with pytest.

### field-mapping

Produce a standard-library Python module that renames and selects JSON fields using a mapping, plus pytest tests.

- Use when: Choose this when fields must be renamed and selected via an explicit source-to-destination mapping.
- Not for: Do not choose this for computed or transformed values: only names and selection change.
- Example requests:
  - Write a Python module that renames and selects JSON fields using a mapping, with tests.
  - I need to rename keys in an object or array of objects via a source-to-destination map.
  - Generate a field-mapping module and test it.

### json-csv-conversion

Produce a standard-library Python module that renders a JSON array of objects as CSV text, plus pytest tests.

- Use when: Choose this when you need a tested function that renders a JSON array of objects as CSV, using the union of keys as the header.
- Not for: Do not choose this when you need the conversion performed on your data now, or when the CSV format must be bespoke (delimiter, quoting rules).
- Example requests:
  - Write a Python function that renders a JSON array of objects as CSV, with tests.
  - I need JSON to CSV with the header being the union of all keys.
  - Generate a JSON-to-CSV module and prove it with pytest.

### json-schema-inference

Produce a standard-library Python module that infers a JSON Schema from sample records, plus pytest tests.

- Use when: Choose this when you need a draft 2020-12 JSON Schema inferred from sample objects, with keys present in every record marked required.
- Not for: Do not choose this for a hand-tuned schema or for constraints the samples do not express (formats, ranges, enums).
- Example requests:
  - Write a Python module that infers a JSON Schema from sample records, with tests.
  - I need a JSON Schema generated from example objects, marking common keys as required.
  - Generate a schema-inference module and prove it with pytest.

### key-normalisation

Produce a standard-library Python module that rewrites JSON object keys to lower snake_case, plus pytest tests.

- Use when: Choose this when object keys must become lower snake_case, with values left untouched.
- Not for: Do not choose this expecting acronym splitting: a capital run like HTTPServer becomes httpserver, not http_server.
- Example requests:
  - Write a Python module that rewrites JSON object keys to lower snake_case, with tests.
  - I need camelCase keys converted to snake_case without changing the values.
  - Generate a key-normalisation module and a pytest suite.

### malformed-record-detection

Produce a standard-library Python module that reports records violating a fixed field contract, plus pytest tests.

- Use when: Choose this when you need one entry per offending record, naming its index and the rule it broke, against a fixed contract.
- Not for: Do not choose this for a contract outside the registered template, or if you need the records corrected rather than reported.
- Example requests:
  - Write a Python module that finds records violating a fixed field contract, with tests.
  - I need a checker that reports the index and failed rule for each bad record.
  - Generate a malformed-record detector and prove it with pytest.

### markdown-table-rendering

Produce a standard-library Python module that renders JSON records as a Markdown table, plus pytest tests.

- Use when: Choose this when JSON records must become a GitHub-flavoured Markdown table with pipes escaped.
- Not for: Do not choose this for HTML tables, spreadsheet formats, or column alignment rules beyond the template.
- Example requests:
  - Write a Python module that renders JSON records as a GitHub Markdown table, with tests.
  - I need a Markdown table renderer that escapes pipes so data cannot break the table.
  - Generate a Markdown-table module and test it.

### metadata-extraction

Produce a standard-library Python module that extracts key/value metadata from a document head, plus pytest tests.

- Use when: Choose this when 'key: value' metadata must be read from the head of a text document, preserving duplicate keys rather than overwriting.
- Not for: Do not choose this for YAML/TOML front matter parsing or for metadata spread through the body.
- Example requests:
  - Write a Python module that extracts 'key: value' metadata from a document head, with tests.
  - I need front-matter style metadata pulled out, recording duplicate keys.
  - Generate a metadata-extraction module and test it.

### nested-flattening

Produce a standard-library Python module that flattens a nested object into dotted-path keys, plus pytest tests.

- Use when: Choose this when a nested object must become single-level dotted-path keys, leaving lists as leaves.
- Not for: Do not choose this if you need lists indexed into keys (a.0, a.1) or a custom separator: the template fixes the behaviour.
- Example requests:
  - Write a Python module that flattens a nested object into dotted-path keys, with tests.
  - I need nested JSON flattened to single-level keys like a.b.c.
  - Generate a flattening module and prove it with pytest.

### python-multifile-package

Produce a small multi-module Python package from a registered, deterministic template: an implementation module, a public facade, a pytest suite, and a README.

- Use when: Choose this when the deliverable is a package rather than one file: a facade, an implementation module, a test suite, and a README, from a registered template.
- Not for: Do not choose this for a single module (use python-utility-module) or for a package whose structure or behaviour is bespoke: only the registered template's shape is produced.
- Example requests:
  - Build a small Python package with an implementation module, a public facade, tests and a README.
  - I need a multi-file Python deliverable, not a single script.
  - Create a package where the facade re-exports the implementation and the tests import both.

### python-utility-module

Produce a small standard-library Python module from a registered, deterministic template, plus the pytest tests that verify it.

- Use when: Choose this when you need one small, importable standard-library Python module whose behaviour matches a registered template, delivered with a passing pytest suite you can re-run yourself.
- Not for: Do not choose this for a multi-file package (use python-multifile-package), for code needing third-party packages, or when you cannot name a registered template: the behaviour is fixed by the template and an unregistered request is rejected rather than guessed.
- Example requests:
  - Write me a small Python function that turns a title into a URL slug, with tests.
  - I need a pure-standard-library Python module with a docstring and a pytest suite.
  - Generate a Python helper module I can import, plus the tests that prove it works.

### readme-generation

Produce a standard-library Python module that generates a Markdown README from function signatures, plus pytest tests.

- Use when: Choose this when a Markdown README must be produced from a list of function signatures, one section each.
- Not for: Do not choose this for prose documentation or API references beyond signature-derived sections.
- Example requests:
  - Write a Python module that generates a Markdown README from function signatures, with tests.
  - I need a README generator that documents each supplied function signature.
  - Generate a README-generator module and prove it with pytest.

### record-deduplication

Produce a standard-library Python module that removes duplicate objects from a JSON array, plus pytest tests.

- Use when: Choose this when duplicates must be removed from a JSON array, keeping the first occurrence and preserving order, optionally on a key subset.
- Not for: Do not choose this for fuzzy matching or similarity-based deduplication: the comparison is exact.
- Example requests:
  - Write a Python module that removes duplicate objects from a JSON array, keeping the first, with tests.
  - I need deduplication by a key subset that preserves input order.
  - Generate a dedupe module and a pytest suite for it.

### regex-from-examples

Produce a standard-library Python module that builds a regular expression from positive and negative examples, plus pytest tests.

- Use when: Choose this when a regular expression must be derived from examples using the shared literal prefix, correctly escaped.
- Not for: Do not choose this expecting a general regex synthesiser: it uses the longest literal prefix shared by the positive examples, and negative examples are used for checking, not for general inference.
- Example requests:
  - Write a Python module that builds a regex from positive and negative examples, with tests.
  - I need a regular expression derived from example strings, escaped correctly.
  - Generate a regex-builder module and prove it with pytest.

### regression-suite-generation

Produce a standard-library Python module that turns recorded input/output pairs into a pytest module, plus pytest tests.

- Use when: Choose this when recorded input/output pairs must become one deterministic pytest case per pair.
- Not for: Do not choose this to test behaviour not covered by the recorded pairs, or to generate non-deterministic tests.
- Example requests:
  - Write a Python module that turns recorded input/output pairs into a pytest module, with tests.
  - I have input/output examples and want a deterministic regression test suite.
  - Generate a regression-suite generator and prove it with pytest.

### text-parser-module

Produce a standard-library Python module that parses a text format into a structured result, plus pytest tests including malformed input. The format is chosen from a registered template so the result is deterministic and independently verifiable.

- Use when: Choose this when you need a standard-library parser for a registered text format, delivered with tests that include malformed input.
- Not for: Do not choose this for a bespoke grammar the templates do not cover, or for formats needing a third-party parser library.
- Example requests:
  - Write a Python module that parses a key=value config file into a dict, with tests for malformed input.
  - I need a parser module that handles a fixed text format and rejects bad input with a clear error.
  - Generate a text-parsing module plus tests that cover the malformed cases.

### webhook-payload-validation

Produce a standard-library Python module that validates a webhook payload envelope, plus pytest tests.

- Use when: Choose this when an incoming webhook envelope must be validated to the registered shape and rejected with structured errors.
- Not for: Do not choose this for provider-specific signature verification or for a schema that differs from the registered envelope.
- Example requests:
  - Write a Python module that validates a webhook JSON envelope and returns structured errors, with tests.
  - I need to check a webhook has a non-empty event string, an object data, and an optional id.
  - Generate a webhook-validation module and its pytest suite.

### xml-json-conversion

Produce a standard-library Python module that converts an XML document into JSON, plus pytest tests.

- Use when: Choose this when you need a tested, standard-library XML-to-JSON conversion that keeps attributes as '@name' keys and collects repeated elements.
- Not for: Do not choose this when the document uses DTDs, external entities, or namespaces: those are not resolved. It is also a code deliverable, not a conversion of your specific file.
- Example requests:
  - Write a Python module that converts an XML document into JSON, with tests.
  - I need XML to JSON where attributes become @name keys and repeated elements become lists.
  - Generate an XML-to-JSON converter and test it, including malformed XML.

## Rules for agents

1. Preflight before authorizing. Never assume a price; read the quote.
2. Send an `Idempotency-Key` when authorizing, so a retry does not create a second job.
3. Treat a job in a terminal state (`completed`, `failed`, `timed_out`, `cancelled`,
   `rejected`) as final. A2A terminal states cannot accept further messages.
4. Read the verification result. A deliverable with `verification.ok = false` is a
   failed job, not a partial success.
5. Do not submit credentials or personal data.
6. Keep the `access_token` returned by authorization. Present it as the
   `X-Job-Token` header (or a `token` query parameter) to read or list your job.
   A job is visible only to the token that authorized it.

## Honest status

- Execution gate on this host: **closed**.
- Payment: **not configured** on this build. No charge can occur. Quotes and acceptances are recorded for audit only.
- All prices are **provisional and unvalidated**.
- There are no accounts or API keys. A per-job access token, issued at
  authorization, is the only credential and it grants access to that one job.

## Source

- Repository: https://github.com/Mahmoudaly187/swishrjobs