Riferimento degli SDK per cartucce

CapDAG separa il runtime delle cartucce, neutrale rispetto al linguaggio, dai contratti dati a livello di cartuccia. Usa CapDAG per costruire e ospitare una cartuccia. Aggiungi un SDK per cartucce CapDAG quando servono i payload LLM condivisi, la policy dei prompt, la selezione delle pagine, la policy di retry o gli altri helper condivisi.

Scegli un pacchetto

Le implementazioni CapDAG Rust, Go, Swift/Objective-C, Python e JavaScript condividono i contratti di URN, definizioni, dispatch e planning. Gli scaffold del runtime delle cartucce sono disponibili per Rust, Go, Swift e Python; JavaScript offre oggi la parità della libreria protocollo e del planner, non uno scaffold per cartucce.

Inizia da Costruisci la tua prima cartuccia. Il riferimento CapDAG documenta runtime, input e output, peer invocation e progresso e logging.

Runtime Python

Installa Python 3.11 o successivo e il runtime pubblico:

python3 -m pip install capdag

Il progetto creato da capdag new NOME --python è l’esempio operativo canonico. Il suo schema centrale è:

from capdag.bifaci.cartridge_runtime import Request, WET_KEY_REQUEST
from ops import DryContext, Op, OpMetadata, WetContext

class MyOp(Op):
    async def perform(self, dry: DryContext, wet: WetContext) -> None:
        request: Request = wet.get_required(WET_KEY_REQUEST)
        payload = request.take_input().collect_all_bytes()
        output = request.emitter()
        output.start(False)
        output.finish(1.0, "complete")
        output.emit_cbor(payload.decode("utf-8"))

    def metadata(self) -> OpMetadata:
        return OpMetadata.builder("MyOp").build()

take_input() trasferisce la proprietà del pacchetto di input e può essere chiamato una sola volta. collect_all_bytes() è adatto a un input scalare e limitato; usa le API stream del riferimento CapDAG quando i dati devono restare incrementali. emitter() restituisce l’emettitore della risposta. Un handler che delega il lavoro usa request.peer() e deve inoltrare correttamente il progresso quando il peer emette log.

Costruisci il manifest con CapManifest, Cap, CapArg, CapOutput e le sorgenti degli argomenti. Ogni manifest include CAP_IDENTITY; il runtime ne fornisce l’handler. Costruisci una Cap URN personalizzata con CapUrnBuilder, conserva la stringa canonica .to_string() e registra l’operazione con quel valore esatto:

runtime = CartridgeRuntime.with_manifest(build_manifest())
runtime.register_op_type(CAP_URN, MyOp)
runtime.run()

Il runtime crea una nuova operazione registrata per ogni richiesta. Conserva lo stato della richiesta nelle variabili locali o nel WetContext.

SDK di prodotto Rust

capdag-cartridge-sdk riesporta capdag e aggiunge questi moduli:

Richiesta LLM

use capdag_cartridge_sdk::llm::LlmGenerationRequest;

let request = LlmGenerationRequest::with_defaults(
    "Riassumi questo documento",
    "hf:Qwen/Qwen2.5-0.5B-Instruct",
);
let json = request.to_json();

prompt e model_spec sono obbligatori. I campi opzionali sono request_type, system_prompt, request_id, max_tokens, temperature, top_k, top_p, min_p, seed, grammar, json_schema, constraint, chat_template, stop_sequences, max_context_length, batch_size, rope_freq_base, rope_freq_scale, repeat_penalty e hf_token. Il token Hugging Face serve per un repository gated e viene inoltrato al download.

with_defaults seleziona la generazione e imposta max_tokens=512, temperature=0.7, top_k=40, top_p=0.9, min_p=0.05, seed=42, max_context_length=0 (dimensionamento automatico), batch_size=2048, rope_freq_base=10000, rope_freq_scale=1 e repeat_penalty=1.1.

ConstraintSpec supporta JSON Schema, espressioni regolari, grammatiche e tool call. RequestType può essere Generate, GetVocab o GetInfo; un valore assente equivale a Generate.

Stream e metadati LLM

Il tipo di output è media:fmt=ndjson;llm-text-stream. Ogni riga è un LlmStreamMessage: Token, Status, Complete, ToolRequest o Error. to_line() e from_line() serializzano e analizzano un record NDJSON.

LlmVocabResponse contiene vocab e vocab_size opzionale. LlmModelInfo contiene model_spec e vocab_size obbligatori, oltre a context_length, embedding_dim, file_size_bytes, head_count, layer_count, supports_chat e supports_tools opzionali.

Le costanti media corrispondenti sono MEDIA_LLM_GENERATION_REQUEST, MEDIA_LLM_TEXT_STREAM, MEDIA_LLM_VOCAB_RESPONSE e MEDIA_LLM_MODEL_INFO_RESPONSE. Lo SDK esporta anche le Cap URN per inferenza GGUF, MLX, Candle e vincolata, vocabolario, informazioni modello, embedding, dimensioni embedding e descrizione immagini. Usa le costanti invece di copiarne i valori serializzati.

backend_for_model_spec sceglie MLX per mlx-community o ;mlx, GGUF per una specifica che contiene gguf, e Candle negli altri casi.

Policy condivise

parse_index_range accetta segmenti one-based N, A-B e A- separati da virgole. Conserva l’ordine scritto, elimina i duplicati successivi, limita una fine oltre il documento e rifiuta zero, intervalli inversi, segmenti non validi, documenti vuoti e intervalli che iniziano dopo l’ultima pagina. Gli indici restituiti sono zero-based. Una selezione assente o vuota restituisce tutte le pagine.

La policy di retry predefinita compie quattro tentativi totali, parte da 250 ms, limita il backoff esponenziale a 10 secondi e rispetta un Retry-After numerico fino a 30 secondi. La policy di download compie cinque tentativi con base 500 ms, limite di backoff 30 secondi e limite Retry-After 60 secondi. Gli status HTTP ripetibili sono 408, 425, 429, 500, 502, 503 e 504; sono transitori anche timeout, errori di connessione, DNS e invio della richiesta. Errori di autenticazione, 404, altre risposte permanenti e l’ultimo tentativo fallito ritornano invariati al chiamante.

La classificazione prompt usa il template chat solo per chat-template-jinja e chat-template-short. Un template assente o ignoto usa testo completion grezzo e scarta il system prompt. La cartuccia backend esegue il rendering; lo SDK condivide la decisione.

SDK di prodotto Go

go get github.com/machinefabric/capdag-cartridge-sdk-go

import "github.com/machinefabric/capdag-cartridge-sdk-go/llm"

request := llm.NewGenerationRequestWithDefaults(
    "Riassumi questo documento",
    "hf:Qwen/Qwen2.5-0.5B-Instruct",
)
body := request.ToJSON()

Il pacchetto Go rispecchia i contratti Rust per richiesta, vincoli, tool, stream, vocabolario, informazioni modello, costanti Media e Cap e classificazione backend. I valori opzionali usano puntatori. Analizza un record stream con llm.FromLine e serializzalo con ToLine. Lo SDK Rust definisce questi tipi wire specifici di CapDAG.

SDK di prodotto Swift e Objective-C

import CapDAGCartridgeSDK
import CapDAGCartridgeSDKSwift

CapDAGCartridgeSDK dipende dai prodotti CapDAG e Bifaci di capdag-objc. CSCartridgeCaps è una collezione ordinata e secure-codable di valori CSCap. addCap(_:) aggiunge una capacità, caps restituisce i valori ordinati e capUrns() restituisce le loro stringhe URN. Analizza quelle stringhe con CSCapUrn; non instradarle confrontando stringhe grezze.

Il prodotto solo Swift rispecchia RefinedDims, PromptStrategy, classifyPrompt e DEFAULT_SYSTEM_PROMPT del modulo prompt Rust.

Regole per le URN

Cap e Media URN sono Tagged URN, non stringhe MIME ad hoc. Le virgolette attorno ai valori direzionali fanno parte della Cap URN canonica e l’ordine dei tag viene normalizzato. Costruisci e analizza le URN con le API CapDAG. Consulta i riferimenti normativi struttura Cap URN e Media URN.