Annotations

Carver Horizon generates AI-powered annotations for each regulatory entry. Annotations provide structured insights — impact scores, urgency ratings, relevance classifications, and business impact summaries — that let you prioritize and route regulatory updates programmatically.

What Annotations Contain

Each annotation is linked to a specific entry and contains:

Field	Type	Description
scores.impact	float (0–1)	How significant this regulation is likely to be
scores.urgency	float (0–1)	How time-sensitive the action required is
scores.relevance	float (0–1)	How relevant to your configured focus areas
classification.update_type	string	Type of change (e.g., new_requirement, amendment, guidance)
classification.regulatory_source	string	Issuing body name
metadata.tags	list[string]	Topic tags
metadata.impact_summary	string	One-paragraph AI-generated summary of business impact
metadata.impacted_business	list[string]	Business functions or sectors affected
metadata.critical_dates	list[string]	Key compliance deadlines

Fetching Annotations via API

Use the /api/v1/feeds/annotations endpoint directly:

# Annotations for a specific topic
curl -H "X-API-Key: your-api-key" \
  "https://app.carveragents.ai/api/v1/feeds/annotations?topic_ids=topic-uuid"

# Annotations for specific entries
curl -H "X-API-Key: your-api-key" \
  "https://app.carveragents.ai/api/v1/feeds/annotations?entry_ids=entry-uuid-1,entry-uuid-2"

Fetching Annotations via SDK

from dotenv import load_dotenv
from carver_feeds import get_client

load_dotenv()
client = get_client()

# Get annotations for entries in a topic
annotations = client.get_annotations(topic_ids=["topic-uuid"])

for annotation in annotations:
    entry_id = annotation["entry_id"]
    impact = annotation["scores"]["impact"]
    summary = annotation["metadata"]["impact_summary"]
    print(f"Entry {entry_id}: impact={impact:.2f} — {summary[:80]}...")

Filtering by Score Thresholds

To surface only high-impact entries, filter annotations by score after fetching:

from dotenv import load_dotenv
from carver_feeds import get_client

load_dotenv()
client = get_client()

annotations = client.get_annotations(topic_ids=["topic-uuid"])

# Keep only high-impact, high-urgency items
critical = [
    a for a in annotations
    if a["scores"]["impact"] >= 0.8 and a["scores"]["urgency"] >= 0.7
]

print(f"Found {len(critical)} critical items requiring immediate attention")
for item in critical:
    dates = item["metadata"].get("critical_dates", [])
    print(f"  Deadlines: {dates}")
    print(f"  Impact: {item['metadata']['impact_summary']}")

Combining Entries with Annotations

A common pattern is fetching entries and their annotations together, then joining on entry_id:

import pandas as pd
from dotenv import load_dotenv
from carver_feeds import get_client

load_dotenv()
client = get_client()

topic_id = "topic-uuid"

# Fetch entries and annotations in parallel
entries = client.get_topic_entries(topic_id=topic_id)
annotations = client.get_annotations(topic_ids=[topic_id])

# Build lookup dict
annotation_by_entry = {a["entry_id"]: a for a in annotations}

# Enrich entries with annotation data
for entry in entries:
    ann = annotation_by_entry.get(entry["id"])
    if ann:
        entry["impact_score"] = ann["scores"]["impact"]
        entry["impact_summary"] = ann["metadata"].get("impact_summary", "")
        entry["critical_dates"] = ann["metadata"].get("critical_dates", [])

# Sort by impact score
entries.sort(key=lambda e: e.get("impact_score", 0), reverse=True)