Actor Quality Guard

Evaluate whether an Apify Actor is structurally sound, machine-discoverable, commercially ready, and safe to publish — and get a machine-readable quality report, not vague advice.

Give me: one or more Actor assessments (manifest, schemas, capability card, README, pricing, examples, run evidence). I reliably return: a deterministic quality report per Actor with per-dimension scores, severity-graded findings, blocking defects, and publication/pricing/discovery recommendations.

What it evaluates

Six quality dimensions, 28 rules (rule set aqg-rules-v0.1.1):

Dimension	Weight	What it checks
Contract integrity	25%	Valid manifest/schemas, required fields, input/output compatibility, capability claims supported, no contradictions
Machine discovery	15%	Clear title/description, categories/keywords, valid examples, supported vs unsupported behavior
Execution readiness	20%	Runnable entrypoint, deterministic output structure, partial-failure isolation, stable identifiers
Commercial readiness	15%	Explicit pricing, billing tied to useful stored output, no synthetic charges, price unknown without benchmark
Trust and safety	15%	No embedded credentials, declared network behavior, provenance, unknowns reported as unknown
Store readiness	10%	README completeness, examples, limitations, API guidance, buyer-facing value proposition

Severity levels

• BLOCKER — must be resolved before publication. A blocker always forces status BLOCKED, regardless of the numerical score.
• HIGH / MEDIUM / LOW — graded findings that lower the score and produce repair actions.
• INFO — reported for transparency; never fails a check.

Assessment statuses

PASS · PASS_WITH_WARNINGS · REPAIR_REQUIRED · BLOCKED · INSUFFICIENT_EVIDENCE · FAILED

A numerical score never overrides a blocking defect. Missing evidence is reported as unknown — never interpreted as a pass.

Intended users

• Foundry operators deciding whether an Actor is ready for Store publication.
• Machine pipelines that gate publication, pricing, or promotion on quality evidence.
• The Capability Contract Repair Bridge, which consumes this report's findings to generate repair bundles.

Relationship to the bridges

• Portfolio Activation Bridge assembles portfolio-level activation inputs from canonical contracts. Quality Guard evaluates individual Actors against quality rules.
• Capability Contract Repair Bridge produces repair bundles for incomplete contracts. Quality Guard scores Actors and identifies findings; a repair bundle can be attached as evidence, and the Guard reports which findings the bundle actually resolves (and which it does not).
• No duplication: the Guard never rewrites contracts or generates repair patches — it measures and reports.

Input example

{
  "assessments": [
    {
      "actorRef": {"actorId": "abc123", "slug": "page-metadata-extractor", "name": "Page Metadata Extractor"},
      "correlationId": "batch-1",
      "manifest": {"name": "page-metadata-extractor", "title": "Page Metadata Extractor",
                   "description": "Turn public webpage URLs into structured metadata records."},
      "inputSchema": {"type": "object",
                      "properties": {"urls": {"type": "array", "items": {"type": "string"}}},
                      "required": ["urls"]},
      "outputSchema": {"type": "object",
                       "properties": {"url": {"type": "string"}, "title": {"type": "string"}}},
      "pricing": {"pricingModel": "PAY_PER_EVENT",
                  "events": {"page-processed": {"priceUsd": 0.001}}},
      "readme": "# Page Metadata Extractor\n\n## Input\n\n## Output\n\n## Limitations\n\n...",
      "exampleInput": {"urls": ["https://example.com"]},
      "exampleOutput": {"url": "https://example.com", "title": "Example"}
    }
  ]
}

Up to 25 assessments per run. Invalid items are isolated as FAILED records — the batch never fails wholesale. The correlationId you supply is preserved in the report.

Output example

Each report contains:

{
  "actorRef": {"actorId": "abc123", "slug": "page-metadata-extractor", "name": "Page Metadata Extractor"},
  "correlationId": "batch-1",
  "assessmentStatus": "REPAIR_REQUIRED",
  "qualityScore": 72,
  "qualityGrade": "C",
  "dimensionScores": {"contract_integrity": 100, "machine_discovery": 80, "...": 0},
  "passedChecks": ["CI-001", "CI-002"],
  "findings": [{"ruleId": "CR-001", "dimension": "commercial_readiness", "severity": "HIGH",
                "passed": false, "detail": "No pricing configuration", "evidenceRef": "pricing"}],
  "blockingDefects": [],
  "recommendedRepairs": [{"ruleId": "CR-001", "severity": "HIGH",
                          "action": "Pricing configuration explicit", "detail": "..."}],
  "missingEvidence": ["benchmarkEvidence"],
  "publicationRecommendation": "DO_NOT_PUBLISH — repair required findings before publication",
  "pricingRecommendation": "Price UNKNOWN — benchmark required before pricing",
  "discoveryRecommendation": "Improve discovery: add categories, add keywords",
  "reportId": "aqg-9f2c…",
  "digest": "sha256…",
  "contractVersion": "aqg-report-v0.1",
  "ruleSetVersion": "aqg-rules-v0.1.1",
  "generatedAt": "2026-10-12T…Z"
}

Reports are pushed to the default dataset; a run summary is stored as SUMMARY in the key-value store.

Score interpretation

Grade	Score	Meaning
A	90–100	Meets the quality bar
B	75–89	Good, minor gaps
C	60–74	Usable with repairs
D	40–59	Significant gaps
F	0–39	Not ready

Blocker behavior

Any BLOCKER-severity failure (missing manifest, missing input schema, synthetic-only billing, embedded credentials) forces status BLOCKED and a DO_NOT_PUBLISH recommendation — even if the numerical score is high. Blockers are listed in blockingDefects and each gets a repair action.

Billing semantics

Pay-per-event: quality-report-produced.

• quality-report-produced is charged only after a valid quality report has been stored.
• quality-report-produced is never charged for FAILED or BLOCKED reports, malformed input, or unstored reports.
• The custom event price is $0.001 per stored, non-blocked, non-failed quality report ($1.00 per 1,000).
• Within one run, a report digest is charged quality-report-produced at most once.
• Two Apify synthetic events are also enabled. apify-default-dataset-item costs $0.00001 for every report written to the dataset, including BLOCKED and FAILED reports, so a stored BLOCKED report costs $0.00001 rather than $0. apify-actor-start costs $0.00005 per GB of run memory (minimum one event) once per run: $0.00005 at the default 1024 MB.
• Platform usage is included; the user does not pay separate compute charges.

Limitations

• Evaluates repository-recorded or caller-supplied evidence only. It does not fetch live Store state.
• Credential scanning is pattern-based; it detects credential-like keys with secret-like values, not all exfiltration vectors.
• Example validation is structural (required fields, rough types), not full JSON Schema validation.
• Network/proxy behavior is assessed from documentation, not observed traffic.
• Scores are comparative within one rule set version; the rule set is re-versioned whenever weights or detection logic change. aqg-rules-v0.1.1 (2026-10-24) keeps the v0.1 weights and adds recognition of standard Apify schema formats (see below).
• Output-contract recognition: outputSchema / datasetSchema pass as present when they are plain JSON Schemas (type), standard Apify dataset schemas (actorSpecification with fields or views), or standard Apify output schemas (actorOutputSchemaVersion with properties). Stable-identifier and provenance checks read record fields from the dataset schema's fields.properties (or view field lists), and accept names such as *Id, *Sha256, url, sourceUrl, finalUrl.
• Contradiction detection is limited to the specific checks in the rule set (for example example-input vs input schema). It does not compare README prose against pricing, so a README-vs-pricing contradiction can go unreported.

API usage

curl -X POST "https://api.apify.com/v2/acts/<actor-id>/runs?token=<token>" \
  -H "Content-Type: application/json" \
  -d '{"assessments": [<assessment objects>]}'

Read results from the run's default dataset; read SUMMARY from the key-value store for counts.

Python client usage

from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("<actor-id>").call(run_input={"assessments": [assessment]})
items = list(client.dataset(run["defaultDatasetId"]).iterate_items())

MCP / agent consumption

The report is plain JSON with stable rule IDs (CI-001, MD-003, …), severity levels, and deterministic reportId/digest values. Agents can:

1. Call the Actor with assessment payloads.
2. Filter blockingDefects to gate publication.
3. Feed recommendedRepairs into the Capability Contract Repair Bridge.
4. Compare digest values to detect quality drift across runs.

Lifecycle

PUBLISHED — locally tested, cloud benchmarked, priced, Store-listed, and verified through a public example task on 2026-10-12. Actor ID: 7Z3j9zAdh5XfR0DV9.