Quick Start

13. Quick Start#

Using the package is three steps: build a client, submit metadata, and retrieve the results.

13.1. Step 1 — build a client#

Pick the factory method for your provider. Each returns a ready-to-use client.

13.1.1. OpenAI#

from ai4data.metadata.reviewer import MetadataReviewerClient

client = MetadataReviewerClient.from_openai(
    model="gpt-4o",
    api_key="sk-...",
)

13.1.2. Anthropic Claude#

client = MetadataReviewerClient.from_anthropic(
    model="claude-sonnet-4-6",
    api_key="sk-ant-...",
)

13.1.3. Azure OpenAI#

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = MetadataReviewerClient.from_azure(
    model="gpt-4o",
    azure_endpoint="https://<resource>.openai.azure.com/",
    azure_deployment="<deployment>",
    api_version="2024-02-01",
    azure_ad_token_provider=token_provider,
)

13.1.4. Ollama (local)#

client = MetadataReviewerClient.from_ollama(
    model="llama3.2",
    port=11434,  # host defaults to http://localhost
)

13.2. Step 2 — submit metadata#

Call submit() with your metadata (a dict or a JSON string). It returns a Job handle immediately; the five-agent pipeline runs in a background thread.

job = client.submit(metadata_dict)
print(job)  # Job(id='...', status='running')

13.3. Step 3 — retrieve the results#

Block until the job finishes with job.wait_sync(timeout=...). It returns the list of detected issues, or raises RuntimeError if the job failed or was cancelled.

result = job.wait_sync(timeout=300)

for issue in result:
    print(f"[{issue['issue_severity']}/5] {issue['detected_issue']}")
    print(f"  Category: {issue['issue_category']}")
    print(f"  Current: {issue['current_metadata']}")
    print(f"  Suggested: {issue['suggested_metadata']}")

13.4. A complete worked example#

The following end-to-end example reviews a single indicator metadata record. The values are illustrative; substitute your own.

13.4.1. Input metadata#

metadata = {
    "series_description": {
        "idno": "WB_WDI_NY.GDP.PCAP.CD",
        "name": "GDP per capita (curent US$)",
        "database_id": "WDI",
        "measurement_unit": "Constant 2015 US$",
        "periodicity": "Annual",
        "definition_long": (
            "GDP per capita is gross domestic product divided by "
            "midyear population, expressed in current US dollars."
        ),
        "aggregation_method": "Weighted average",
        "time_coverage": "1960-2023",
    }
}

13.4.2. Run it#

from ai4data.metadata.reviewer import MetadataReviewerClient

client = MetadataReviewerClient.from_anthropic(
    model="claude-sonnet-4-6", api_key="sk-ant-...",
)

job = client.submit(metadata)
issues = job.wait_sync(timeout=300)

13.4.3. Representative output#

The pipeline returns a ranked list. Here the run finds a typo and a unit contradiction (the name and definition_long both say current US dollars, but measurement_unit says constant 2015 US$):

[
  {
    "detected_issue": "Typo in series name: 'curent' should be 'current'.",
    "issue_category": "Typo / Language",
    "issue_severity": 2,
    "current_metadata": {"series_description.name": "GDP per capita (curent US$)"},
    "suggested_metadata": {"series_description.name": "GDP per capita (current US$)"}
  },
  {
    "detected_issue": "Measurement unit contradicts the name and definition, which both state current US dollars.",
    "issue_category": "Inconsistency / Conflict",
    "issue_severity": 4,
    "current_metadata": {"series_description.measurement_unit": "Constant 2015 US$"},
    "suggested_metadata": {"series_description.measurement_unit": "Current US$"}
  }
]

Note

What you will NOT see Notice the example has no issue raised about idno or about the date format in time_coverage. Those fall under the built-in exclusion rules (Advanced Usage): the idno field is excluded entirely, and formatting/style-only differences are filtered by the critic. This is by design — the pipeline favors actionable content errors over cosmetic noise.

Contents