Tutorial API Claude Opus 4.7: creare un digitalizzatore di grafici

La scorsa settimana è stato rilasciato Claude Opus 4.7, l’ultima iterazione del modello di punta di Anthropic. Grazie a un aumento di circa tre volte della risoluzione visiva e a una maggiore aderenza letterale a prompt complessi, Opus 4.7 è progettato per muoversi con precisione chirurgica tra interfacce utente intricate e per analizzare diagrammi tecnici ad alta fedeltà.

In questo tutorial ti guiderò attraverso i principali cambiamenti introdotti in Claude Opus 4.7. Vedremo cos’è il modello, le nuove funzionalità chiave e come configurarlo in locale con Python. Infine, costruiremo un progetto dimostrativo completo e multi-step: un digitalizzatore autonomo di grafici visivi ad alta risoluzione.

Se vuoi saperne di più sui large language model (LLM) di Anthropic, ti consiglio il corso Introduzione ai modelli Claude.

Che cos’è Claude Opus 4.7?

Claude Opus 4.7 è il più recente LLM di punta di Anthropic. Poiché l’azienda limita il più potente Claude Mythos Preview ai soli esperti di sicurezza approvati, Opus 4.7 rimane la principale interfaccia API ampiamente disponibile per gli sviluppatori generici.

Questa versione porta aggiornamenti in diverse aree: 

• Interpretazione dei dati visivi
• Logica matematica
• Rispetto delle istruzioni
• Memorizzazione di contenuti da ambienti di coding complessi 

Gli sviluppatori notano miglioramenti marcati nella capacità di seguire istruzioni rigorose ed evitare loop di elaborazione ripetitivi. Opus 4.7 ricontrolla intrinsecamente il proprio lavoro e rivede le ipotesi prima di scrivere codice, riducendo notevolmente le probabilità che gli agenti restino bloccati in loop di errore continui.

Guardando i benchmark, spicca un risultato. Nel test impegnativo SWE-bench Pro, che misura quanto bene un’IA corregge bug reali di software open-source su GitHub, Opus 4.7 ha ottenuto un aumento di 10,9 punti rispetto al suo predecessore. Questo salto consolida il ruolo della famiglia di modelli Opus come riferimento per la programmazione agentica.

Per saperne di più sul modello, consulta la nostra guida a Claude Opus 4.7.

Novità di Claude Opus 4.7

Il passaggio a Opus 4.7 introduce nuovi piani di controllo per gestire le risorse computazionali e alcuni cambiamenti nel prompt engineering. Ecco le principali novità che devi conoscere:

• Visione multimodale ad alta risoluzione: Il modello porta la dimensione massima accettata dell’immagine a 2.576 pixel sul lato più lungo, per una risoluzione effettiva di circa 3,75 megapixel. La mappatura delle coordinate geometriche è stata riprogettata: le coordinate dei bounding box ora hanno un mapping 1:1 rigidamente applicato con i pixel reali dell’immagine, eliminando la necessità di complessi calcoli di fattori di scala.

• Adaptive thinking: I budget di thinking estesi (ad es. budget_tokens) sono stati completamente rimossi. L’invio di richieste legacy restituirà un errore HTTP 400. Al loro posto, Opus 4.7 impone l’uso dell’“adaptive thinking” (thinking: {"type": "adaptive"}), che permette al modello di allocare dinamicamente il proprio budget di ragionamento interno in base alla complessità del prompt.

• Controllo granulare dello sforzo: È stato introdotto un nuovo valore di parametro, xhigh (extra alto), matematicamente posizionato tra la configurazione standard high e la massima max. Anthropic raccomanda vivamente xhigh come punto di partenza ottimale per coding agentico e problem solving complesso. Il modello si è anche spostato verso un “letteralismo” assoluto: esegue esattamente il testo fornito senza “leggere tra le righe”.

• Task budgets: Per mitigare matematicamente i loop agentici incontrollati, Opus 4.7 introduce i “task budget” (attualmente in beta pubblica). Definendo un task_budget, gli sviluppatori indicano esplicitamente al modello il totale assoluto di token consentiti per l’intero ciclo di vita del task. Il modello tiene traccia costante del conto alla rovescia e si autoregola per garantire un completamento armonioso.

• Strumento di memoria lato client: Opus 4.7 è eccezionalmente bravo a scrivere e leggere da uno scratchpad gestito. Per formalizzarlo, Anthropic ha migliorato lo strumento di memoria lato client, fornendo funzionalità di sincronizzazione con supporto git ottimizzate per i workflow MemFS (Memory File System).

Configurare un ambiente per Claude Opus 4.7

Prima di iniziare a programmare il nostro progetto demo, dobbiamo predisporre l’ambiente per supportare Opus 4.7. In questo tutorial useremo Python asincrono, lo standard del settore per workflow ad alta intensità di dati e alta concorrenza.

Dobbiamo avere installato Python 3.8 o superiore. Consiglio vivamente di creare un ambiente virtuale isolato per prevenire conflitti di dipendenze.

Ecco come creare e attivare un ambiente chiamato opus_4_7 usando Anaconda:

conda create -n opus_4_7 python=3.10 -y
conda activate opus_4_7

Creare un digitalizzatore autonomo di grafici ad alta risoluzione con Claude Opus 4.7

Per trasformare le capacità teoriche di Claude Opus 4.7 in un’applicazione pratica, costruiremo un digitalizzatore autonomo di grafici ad alta risoluzione.

I data scientist si imbattono continuamente in dati preziosi bloccati come immagini statiche o PDF (come scatter plot, bar chart o line chart). Con i modelli di IA più vecchi serviva scrivere complessi calcoli di fattori di scala per automatizzare l’estrazione dei dati da questi grafici.

In questo progetto costruiremo uno script Python che prende uno screenshot di qualsiasi grafico e crea un file CSV con i dati grezzi. 

In particolare:

• Useremo la nuova visione a 3,75 MP e il mapping pixel 1:1 per leggere perfettamente il grafico.

• Useremo l’adaptive thinking al livello di sforzo xhigh per dedurre rigorosamente gli assi X e Y.

• Produrremo un DataFrame Pandas pulito contenente i punti dati esatti.

Ti guiderò passo dopo passo. Questo tutorial è autosufficiente, ma se vuoi approfondire le capacità del modello o hai difficoltà a implementare i tuoi agenti, consulta la sua documentazione ufficiale.

Passo 1: imposta la chiave API

Per prima cosa dobbiamo abilitare l’autenticazione. Per farlo, creiamo una chiave API sulla Anthropic Developer Console.

Non inserire mai le credenziali API direttamente nel repository del codice sorgente. Genera invece un file .env sicuro nella directory root del progetto:

ANTHROPIC_API_KEY=<paste_your_api_key_here>

Nota che il modello non è gratuito. Per abilitare la chiave API, dobbiamo aggiungere credito all’account. La buona notizia è che i prezzi del modello sono gli stessi dei due modelli precedenti:

Passo 2: installa le dipendenze Python

Ora installiamo le librerie necessarie. Ci serviranno:

• anthropic, l’SDK ufficiale Anthropic per l’integrazione con l’API;

• python-dotenv per la gestione delle variabili d’ambiente;

• pandas per strutturare i dati estratti.

Apri il terminale ed esegui il comando seguente (assicurati che l’ambiente opus_4_7 creato sopra sia attivo):

pip install anthropic python-dotenv pandas

Passo 3: crea un chatbot testuale con adaptive thinking

Impostiamo le basi costruendo una semplice interfaccia a riga di comando asincrona. Questo passo introduce il nuovo livello di sforzo xhigh e l’architettura di adaptive thinking di Opus 4.7. Crea un file chiamato chart_digitizer.py e aggiungi il seguente codice:

import os
import asyncio
from dotenv import load_dotenv
from anthropic import AsyncAnthropic

# Ingest secure environment variables
load_dotenv()

# Initialize the asynchronous Anthropic client
client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

async def test_adaptive_thinking():
    print("Initiating Text Agent with Adaptive Thinking...")
    
    response = await client.messages.create(
        model="claude-opus-4-7",
        max_tokens=64000,
        stream=True, # Required for long responses
        thinking={"type": "adaptive"}, # NEW: Replaces budget_tokens
        output_config={"effort": "xhigh"}, # NEW: Extra high effort level
        messages=[
            {"role": "user", "content": "Explain why 1:1 pixel mapping is crucial for data extraction."}
        ]
    )
    
    # Parse the streaming response structure
    async with response as stream:
        async for event in stream:
            if event.type == "content_block_start":
                if event.content_block.type == "thinking":
                    print("\n--- Internal Reasoning Trace ---")
                elif event.content_block.type == "text":
                    print("\n--- Final Output ---")
            elif event.type == "content_block_delta":
                if event.delta.type == "thinking_delta":
                    print(event.delta.thinking, end="", flush=True)
                elif event.delta.type == "text_delta":
                    print(event.delta.text, end="", flush=True)

if __name__ == "__main__":
    asyncio.run(test_adaptive_thinking())

Possiamo eseguirlo con il comando:

python chart_digitizer.py

Questo script mostra come inviare una richiesta a Claude Opus 4.7, ma non estrae ancora dati da un grafico. Si limita a inviare il prompt:

Explain why 1:1 pixel mapping is crucial for data extraction.

Passo 4: definisci lo schema di estrazione dati

Per garantire che il modello ci fornisca dati puliti utilizzabili in Pandas, useremo uno “Strumento” per imporre un output strutturato. Definiamo uno schema JSON che indica a Claude esattamente come formattare le coordinate estratte dal grafico.

Aggiorna il file chart_digitizer.py per includere lo schema dello strumento e un system prompt dopo l’inizializzazione del client:

# Define the JSON schema to force structured data extraction
extraction_tool = {
    "name": "save_chart_data",
    "description": "Saves the extracted data points from the chart into a structured format.",
    "input_schema": {
        "type": "object",
        "properties": {
            "x_axis_label": {"type": "string", "description": "The label for the X axis"},
            "y_axis_label": {"type": "string", "description": "The label for the Y axis"},
            "data_points": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "x": {"type": "number", "description": "X-axis value"},
                        "y": {"type": "number", "description": "Y-axis value"}
                    },
                    "required": ["x", "y"]
                }
            }
        },
        "required": ["x_axis_label", "y_axis_label", "data_points"]
    }
}

SYSTEM_PROMPT = """
You are an expert Data Scientist. Your task is to digitize the provided chart image.
Execute the following strict, literal directives:
1. Scan the image using your 1:1 pixel mapping capabilities to identify the X and Y axes, their scales, and all plotted data points.
2. Utilize your adaptive thinking space to perform the mathematical conversions from visual pixel locations to the actual chart values.
3. You MUST use the 'save_chart_data' tool to output the final extracted data points. 
Do not guess. Be highly precise.
"""

Per forzare il modello a usare lo strumento e il system prompt, aggiorniamo la richiesta includendo i parametri tool e system:

response = await client.messages.create(
        model="claude-opus-4-7",
        max_tokens=64000,
        stream=True,
        thinking={"type": "adaptive"},
        system=SYSTEM_PROMPT, # Add to enable the system prompt
        tools=[extraction_tool], # Add to provide the tool to the model
        messages=messages,
        output_config={
            "effort": "xhigh",
        }
    )

Passo 5: aggiungi un task budget per il ragionamento visivo complesso

Mappare visivamente centinaia di punti dati e calcolarne i valori esatti richiede uno sforzo cognitivo enorme. Per proteggere i nostri crediti di calcolo, imponiamo un task budget. Stabiliamo un limite consigliato di 80.000 token per questa operazione. 

Possiamo impostare questo limite nella richiesta aggiungendo un task_budget all’output_config:

response = await client.messages.create(
        model="claude-opus-4-7",
        max_tokens=64000,
        stream=True,
        thinking={"type": "adaptive"},
        system=SYSTEM_PROMPT,
        tools=[extraction_tool],
        messages=messages,
        output_config={
            "effort": "xhigh",
            "task_budget": {"type": "tokens", "total": 80000} # Add to limit output tokens
        }
    )

Nota le intestazioni beta necessarie per sbloccare questa funzionalità. Per impostarle, aggiorniamo l’inizializzazione dell’agente in questo modo:

client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
    default_headers={"anthropic-beta": "task-budgets-2026-03-13"}
)

Passo 6: costruisci un digitalizzatore visivo ad alta risoluzione

Nella fase finale integriamo le capacità visive a 3,75 MP. Costruiremo una funzione di utilità robusta per gestire l’ingestione delle immagini e finalizzeremo il codice per produrre un file CSV con i dati. 

Ecco il codice completo e finale del nostro digitalizzatore visivo:

import os
import asyncio
import mimetypes
import sys
from dotenv import load_dotenv
from anthropic import AsyncAnthropic
import base64
import pandas as pd

# Ingest secure environment variables
load_dotenv()

# Initialize the asynchronous Anthropic client
client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
    default_headers={"anthropic-beta": "task-budgets-2026-03-13"}
)

# Define the JSON schema to force structured data extraction
extraction_tool = {
    "name": "save_chart_data",
    "description": "Saves the extracted data points from the chart into a structured format.",
    "input_schema": {
        "type": "object",
        "properties": {
            "x_axis_label": {"type": "string", "description": "The label for the X axis"},
            "y_axis_label": {"type": "string", "description": "The label for the Y axis"},
            "data_points": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "x": {"type": "number", "description": "X-axis value"},
                        "y": {"type": "number", "description": "Y-axis value"}
                    },
                    "required": ["x", "y"]
                }
            }
        },
        "required": ["x_axis_label", "y_axis_label", "data_points"]
    }
}

SYSTEM_PROMPT = """
You are an expert Data Scientist. Your task is to digitize the provided chart image.
Execute the following strict, literal directives:
1. Scan the image using your 1:1 pixel mapping capabilities to identify the X and Y axes, their scales, and all plotted data points.
2. Utilize your adaptive thinking space to perform the mathematical conversions from visual pixel locations to the actual chart values.
3. You MUST use the 'save_chart_data' tool to output the final extracted data points. 
Do not guess. Be highly precise.
"""

def encode_high_res_image(image_path: str) -> tuple[str, str]:
    if not os.path.exists(image_path):
        raise FileNotFoundError(f"Critical Error: Image not located at {image_path}")
    with open(image_path, "rb") as image_file:
        base64_data = base64.b64encode(image_file.read()).decode("utf-8")

    media_type, _ = mimetypes.guess_type(image_path)
    if not media_type or not media_type.startswith("image/"):
        media_type = "image/png"
    return base64_data, media_type

async def digitize_chart(image_path: str = "chart.jpg"):
    print("\nInitiating Opus 4.7 Autonomous Chart Digitization...")
    IMAGE_PATH = image_path
    base64_image_data, media_type = encode_high_res_image(IMAGE_PATH)

    messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": media_type,
                        "data": base64_image_data
                    }
                },
                {
                    "type": "text",
                    "text": "Please digitize this chart and extract the data points."
                }
            ]
        }
    ]

    response = await client.messages.create(
        model="claude-opus-4-7",
        max_tokens=64000,
        stream=True,
        thinking={"type": "adaptive"},
        system=SYSTEM_PROMPT,
        tools=[extraction_tool],
        messages=messages,
        output_config={
            "effort": "xhigh",
            "task_budget": {"type": "tokens", "total": 80000}
        }
    )

    # Accumulate tool input and thinking from the stream
    import json
    tool_name = None
    tool_input_json = ""
    thinking_text = ""

    async with response as stream:
        async for event in stream:
            if event.type == "content_block_start":
                if event.content_block.type == "tool_use":
                    tool_name = event.content_block.name
                    tool_input_json = ""
                elif event.content_block.type == "thinking":
                    thinking_text = ""
            elif event.type == "content_block_delta":
                if event.delta.type == "input_json_delta":
                    tool_input_json += event.delta.partial_json
                elif event.delta.type == "thinking_delta":
                    thinking_text += event.delta.thinking

    if thinking_text:
        print("\n--- Internal Thinking (Math & Scaling) ---")
        print(thinking_text[:500] + "...\n[Cognitive trace truncated]")

    if tool_name == "save_chart_data" and tool_input_json:
        print("\n--- Data Extraction Complete! ---")
        chart_data = json.loads(tool_input_json)
        df = pd.DataFrame(chart_data["data_points"])

        print(f"\nX-Axis: {chart_data['x_axis_label']}")
        print(f"Y-Axis: {chart_data['y_axis_label']}")
        print("\nExtracted DataFrame:")
        print(df.head(10))

        output_path = "chart_data.csv"
        df.to_csv(output_path, index=False)
        print(f"\nDataFrame saved to {output_path}")

if __name__ == "__main__":
    image_path = sys.argv[1] if len(sys.argv) > 1 else "chart.jpg"
    asyncio.run(digitize_chart(image_path))

Per provarlo, ho scaricato da Yahoo Sports questo grafico, che mostra l’affluenza alla Coppa del Mondo FIFA per anno, in un file chiamato fifa.webp: 

Eseguiamo lo script come prima, ma passando il nome dell’immagine del grafico come argomento:

python chart_digitizer.py fifa.webp 

Ecco il risultato:

Extracted DataFrame:
      x        y
0  1930   590000
1  1934   375000
2  1938   375000
3  1950  1040000
4  1954   770000
5  1958   820000
6  1962   890000
7  1966  1560000
8  1970  1600000
9  1974  1870000

Se lo tracciamo, possiamo verificare che è molto accurato anche se il grafico originale non aveva le etichette sull’asse y.

Conclusione

Siamo passati con successo dalla creazione di un semplice chatbot asincrono alla costruzione di un motore di ragionamento visivo altamente robusto per la data science.

Poiché il modello non richiede downsampling, riesce a leggere grafici complessi senza perdere fedeltà sub-pixel. Ti consiglio di testare questo codebase con vari grafici complessi per apprezzarne davvero le capacità!

Testando il modello su più grafici, mi ha colpito in particolare la sua accuratezza. Questo script non va considerato un prodotto finale, perché c’è ancora ampio margine di miglioramento. Se vuoi fare pratica, ecco un paio di suggerimenti:

• Estrai metadati come unità e etichette degli assi: nell’esempio sopra, il grafico mostra 3,5, ma non conosciamo l’unità. Il grafico originale rappresenta 3,5M, cioè 3,5 milioni di persone.
• Abilita il controllo sul numero di punti campionati: il modello ha estratto alcuni punti chiave, ma non il numero di partecipanti per ogni singolo anno.

Se ti interessa programmare usando i modelli di Anthropic, ti consiglio vivamente il nostro corso Software Development with Claude Code!