Intégration SDK
Référence
La taxonomie fermée du SDK, les configurations d'assets typées et le contrat HTTP de l'Intake. Pour les exemples d'usage, voyez les sections précédentes.
Taxonomie
| Enum | Valeurs |
|---|---|
| RecordType | run · payload · metric · log · score · audit |
| AssetKind | llm · model · script · vector_store · tool · judge · api · database · cache · queue · embedding · guardrail · prompt · custom |
| AssetRole | router · analysis · retrieval · proxy · embedding · rerank · guardrail · postprocess · storage · inference · training · feature_engineering · data_quality · custom |
| FlowPhase | routing · preprocess · retrieval · analysis · postprocess · finalize · training · evaluation |
| SpanKind | workflow · agent · task · tool · llm · embedding · retrieval |
| DataRole | input · output · context · artifact · custom |
| DataKind | messages · prompt · system_prompt · prompt_template · guardrail_rule · judge_criteria · completion · retrieval_context · document_chunk · embedding_query · embedding_result · tool_args · tool_result · judge_result · metric_sample · ground_truth · predictions · feature_vector · training_data · reasoning_output · custom |
| DataFormat | text · json · number · boolean · array · object · uri |
| DataSensitivity | public · internal · confidential · restricted |
| JudgeFamily | safety · quality · grounding · compliance · policy · cost · latency · relevance · custom |
| JudgeWhen | live · step_end · flow_end · offline |
| ScoreValueType | number · boolean · string · enum |
| AttachLevel | run · flow · session |
| RetryReason | timeout · rate_limit · server_error · validation · other |
| PromptRole | system · user · assistant · instruction · guardrail_rule · judge_criteria · tool_description · rag_query · few_shot · custom |
| PromptCaptureMode | hash_only · full · redacted |
Métriques standardisées (StandardMetric)
| Catégorie | Clés |
|---|---|
| Tokens | input_tokens · output_tokens · total_tokens · cache_read_tokens · cache_creation_tokens · reasoning_tokens |
| Coût | cost_usd · cost_units |
| Latence | latency_ms · duration_ms · time_to_first_token_ms · tokens_per_second |
| Streaming | stream_chunks · stream_aborted |
| RAG / cache | cache_hit · chunks_retrieved · chunks_relevant |
| Fiabilité | error_count · retry_count · batch_size |
| GPU | gpu_memory_used_mb · gpu_memory_total_mb · gpu_util_percent · gpu_temp_c · gpu_power_watts |
| Rate-limit | ratelimit_remaining_requests · ratelimit_remaining_tokens · ratelimit_reset_*_sec · ratelimit_retry_after_sec |
Configurations d'assets typées
Le champ config d'un Asset est une union discriminée (config_type). Renseignez-la pour exposer
les hyperparamètres au cockpit.
from niaone_sdk.models import Asset, LlmConfigfrom niaone_sdk.enums import AssetKind, AssetRoleasset = Asset(kind=AssetKind.LLM, role=AssetRole.ANALYSIS, name="gpt-4o", provider="openai", config=LlmConfig(temperature=0.7, max_tokens=2048, top_p=0.9, stream=True))| Config | Champs principaux |
|---|---|
| LlmConfig | temperature · top_p · top_k · max_tokens · frequency_penalty · stop_sequences · seed · response_format · stream |
| EmbeddingConfig | dimensions · normalize · truncation_strategy · encoding_format |
| VectorStoreConfig | top_k · similarity_threshold · search_type · chunk_size · chunk_overlap · rerank_model |
| GuardrailConfig | thresholds · categories · action_on_violation · prompt_refs |
| CacheConfig | ttl_seconds · strategy · similarity_threshold |
| PromptConfig | role · content_hash · template_syntax · variables · capture_mode |
Contrat HTTP de l'Intake
| Méthode | Route | Auth | Rôle |
|---|---|---|---|
| POST | /v1/intake/batch | Bearer | Lot de records (202) |
| POST | /v1/intake/record | Bearer | Un record (202) |
| POST | /v1/intake/validate | Bearer | Dry-run de validation |
| GET | /v1/intake/health | — | Santé |
| GET | /v1/intake/capabilities | — | Limites & version de schéma |
| Code | Clé | Cause |
|---|---|---|
| 401 | AUTH_INVALID | Clé API invalide / révoquée |
| 403 | FLOW_FORBIDDEN | Flow definition introuvable ou inactive |
| 413 | PAYLOAD_TOO_LARGE | Dépasse maxPayloadBytes |
| 422 | INVALID_SCHEMA / BATCH_TOO_LARGE | Validation Zod / lot trop grand |
| 429 | RATE_LIMITED | Quota dépassé (champ degraded_mode) |
Quotas & garanties (par SIA)
sustainedRpsTarget, burstRpsMax, maxPayloadBytes (≈ 256 KB), maxBatchCount (100). En-tête
idempotency-key optionnel (dédup scoping tenant+SIA+flow). Lanes standard / fastlane. Réglables
dans Settings → Advanced du SIA.
SDK — pour aller plus loin
Référence complète (taxonomie intégrale, tous les champs des configs, modèle asynchrone) :
sdk/python/README.md et sdk/typescript/README.md. Symboles publics : voir
Référence API.