Référence 3.6.1

Wiki du SDK Igris

Référence du SDK Python réellement exporté par core.sdk. La surface stable contient 4 composants et 11 méthodes. Les types internes utilisés comme paramètres ou retours sont documentés séparément.

Démarrer → Voir l’API complète →

01

Démarrage

Python 3.11 ou plus récent.

Installation du dépôt

python -m pip install -e ".[dev]"

Premier appel

from core.sdk import Igris

igris = Igris("./workspace")

answer = igris.chat(
    "Résume l'état du projet",
    project="mon-projet",
)
print(answer)

Import recommandé

from core.sdk import Igris. Les intégrations doivent éviter d’importer directement les modules internes du runtime.

02

Surface publique

Les symboles présents dans core.sdk.__all__.

Point d’entrée de l’application

Igris

igris

Charge Settings, initialise IgrisService, puis expose missions, projects et sprints.

Igris(workspace="./workspace", *, settings=None)

chat()

Missions et Mission Intake

MissionAPI

igris.missions

Normalise ou exécute une mission et relit le contexte de grilling persistant.

MissionAPI(service: IgrisService)

run()normalize()pending_grill()context()

Façade du Sprint Engine

SprintAPI

igris.sprints

Crée, précise, exécute et relit les Sprints stockés dans le workspace.

SprintAPI(engine: SprintEngine)

create()answer()run()get()list()

Cycle de vie des projets

ProjectAPI

igris.projects

Construit un plan de nettoyage sans effectuer la suppression.

ProjectAPI(settings: Settings)

cleanup_plan()

Contrat stable actuel : __all__ = ["Igris", "MissionAPI", "ProjectAPI", "SprintAPI"]. Settings, RunReport, Sprint et EventSink sont des contrats connexes, mais ne sont pas réexportés par core.sdk.

03

Igris

Point d’entrée, configuration et Chat.

Igris()

#

Igris(workspace: str | Path = "./workspace", *, settings: Settings | None = None)

Paramètre	Type	Défaut	Description
`workspace`	`str \| Path`	"./workspace"	Racine IPRCA chargée lorsque settings n’est pas fourni.
`settings`	`Settings \| None`	None	Configuration déjà construite ; elle prend priorité sur workspace.

Retour : Une instance qui expose settings, service, missions, projects et sprints.

L’initialisation prépare la structure IPRCA via le runtime sous-jacent.

chat()

#

chat(prompt: str, *, project: str | None = None, mission_context_id: str | None = None, conversation_context: list[dict] | None = None, event_sink: EventSink | None = None) -> str

Paramètre	Type	Défaut	Description
`prompt`	`str`	requis	Message utilisateur.
`project`	`str \| None`	None	Projet conversationnel actif.
`mission_context_id`	`str \| None`	None	Mission Intake dont il faut réinjecter le contexte.
`conversation_context`	`list[dict] \| None`	None	Tours précédents fournis explicitement.
`event_sink`	`EventSink \| None`	None	Callback recevant les événements structurés.

Retour : str — réponse conversationnelle finale.

Le Chat peut utiliser les tools en lecture seule autorisés par sa policy ; il ne lance pas automatiquement une mission d’écriture.

04

MissionAPI

Normalisation, exécution et reprise du contexte.

from core.sdk import Igris

igris = Igris("./workspace")

preview = igris.missions.normalize(
    "Crée un rapport avec sources et tests",
    "mon-projet",
)

if preview["status"] == "ready":
    report = igris.missions.run(
        "Crée un rapport avec sources et tests",
        "mon-projet",
    )
    print(report.status, report.run_id)
    print(report.model_dump(mode="json"))

run()

#

missions.run(prompt: str, project: str, *, event_sink: EventSink | None = None, continuation_mission_id: str | None = None, conversation_context: list[dict] | None = None) -> RunReport

Paramètre	Type	Défaut	Description
`prompt`	`str`	requis	Objectif ou clarification à exécuter.
`project`	`str`	requis	Identifiant projet, 1 à 100 caractères alphanumériques, point, tiret ou underscore.
`event_sink`	`EventSink \| None`	None	Flux d’observabilité synchrone.
`continuation_mission_id`	`str \| None`	None	Mission à reprendre après grilling ou interruption.
`conversation_context`	`list[dict] \| None`	None	Contexte conversationnel pour la normalisation.

Retour : RunReport — état complet de l’exécution.

Les statuts possibles incluent completed, partial, blocked, failed, cancelled, interrupted, needs_grilling, awaiting_dependency et awaiting_approval.

normalize()

#

missions.normalize(prompt: str, project: str) -> dict[str, Any]

Paramètre	Type	Défaut	Description
`prompt`	`str`	requis	Demande à compiler en Mission Intake.
`project`	`str`	requis	Projet cible.

Retour : Dictionnaire MissionIntake : status, project_id, mission_id, source_sha256, brief, questions, missing_fields, dépendances et approbation.

Ne lance pas le Mission Runtime. Utile pour prévisualiser le brief et les questions.

pending_grill()

#

missions.pending_grill(project: str) -> dict[str, Any] | None

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet dont il faut rechercher la dernière mission en attente.

Retour : Le dernier enregistrement needs_grilling non terminé, sinon None.

Lit le store workspace/inbox/mission-intake/<project>/.

context()

#

missions.context(project: str, mission_id: str) -> dict[str, Any] | None

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet de la mission.
`mission_id`	`str`	requis	Identifiant Mission Intake.

Retour : mission_id, project_id, source_prompt, questions et missing_fields ; None si absent.

Cette vue bornée est conçue pour réinjecter le contexte utile sans relire tout le store.

05

SprintAPI

Planification et exécution par DAG.

from core.sdk import Igris

igris = Igris("./workspace")
sprint = igris.sprints.create(
    "Créer la page produit, lancer les tests et livrer le rapport",
    "mon-projet",
)

if sprint.status.value == "grilling":
    sprint = igris.sprints.answer(
        "mon-projet",
        sprint.id,
        "Astro, responsive mobile, aucune publication automatique.",
    )

if sprint.status.value == "planned":
    sprint = igris.sprints.run("mon-projet", sprint.id)

print(sprint.status.value, sprint.progress())

create()

#

sprints.create(goal: str, project: str, *, event_sink: EventSink | None = None) -> Sprint

Paramètre	Type	Défaut	Description
`goal`	`str`	requis	Objectif immuable du Sprint.
`project`	`str`	requis	Projet cible.
`event_sink`	`EventSink \| None`	None	Callback de progression.

Retour : Sprint existant de même identité, ou nouveau Sprint en grilling/planned.

La façade publique ne propose pas le paramètre require_po_approval du moteur interne.

answer()

#

sprints.answer(project: str, sprint_id: str, answer: str, *, event_sink: EventSink | None = None) -> Sprint

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet du Sprint.
`sprint_id`	`str`	requis	Identifiant spr-xxxxxxxxxxxx.
`answer`	`str`	requis	Clarification du Product Owner.
`event_sink`	`EventSink \| None`	None	Callback de progression.

Retour : Sprint mis à jour ; l’objectif original reste inchangé.

Lève ValueError si le Sprint n’attend pas de réponse de grilling.

run()

#

sprints.run(project: str, sprint_id: str, *, event_sink: EventSink | None = None) -> Sprint

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet du Sprint.
`sprint_id`	`str`	requis	Sprint à exécuter.
`event_sink`	`EventSink \| None`	None	Événements Sprint et tâches.

Retour : Sprint après exécution par vagues du DAG.

Lève FileNotFoundError si le Sprint est inconnu et ValueError si son état ne permet pas l’exécution.

get()

#

sprints.get(project: str, sprint_id: str) -> Sprint | None

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet du Sprint.
`sprint_id`	`str`	requis	Sprint recherché.

Retour : Sprint Pydantic chargé depuis le store, sinon None.

Une entrée illisible ou invalide est traitée comme absente.

list()

#

sprints.list(project: str) -> list[Sprint]

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet dont il faut lister les Sprints.

Retour : Liste triée des Sprints valides ; liste vide si le projet n’a aucun Sprint.

Lit workspace/inbox/sprints/<project>/.

06

ProjectAPI

Prévisualisation du nettoyage projet.

plan = igris.projects.cleanup_plan(
    "mon-projet",
    purge_generated=False,
)
for target in plan["targets"]:
    print(target["path"], target["reason"])

cleanup_plan()

#

projects.cleanup_plan(project: str, *, purge_generated: bool = False) -> dict[str, Any]

Paramètre	Type	Défaut	Description
`project`	`str`	requis	Projet à analyser.
`purge_generated`	`bool`	False	Inclut assets/generated dans les cibles si activé.

Retour : Plan avec project_id, workspace, generated_at, active_runs, target_count, targets, preserved, database_configured et purge_generated.

Opération de prévisualisation uniquement : aucune suppression n’est exécutée par cette méthode.

07

Contrats retournés

Objets du runtime rencontrés par les consommateurs du SDK.

RunReport

Objet Pydantic renvoyé par missions.run(). Utilisez report.model_dump(mode="json") pour une structure sérialisable.

Champ	Type	Rôle
`run_id`	`str \| None`	Identifiant de run persistant.
`status`	`Literal[9 états]`	État terminal ou attente contrôlée.
`project_id`	`str`	Projet résolu.
`user_prompt`	`str`	Demande reçue.
`free_response`	`str`	Réponse textuelle du runtime.
`compiled`	`ExecutionEnvelope \| None`	Dernière enveloppe compilée.
`rounds`	`list[ExecutionRound]`	Rounds et résultats intermédiaires.
`results`	`list[ToolResult]`	Résultats de tools agrégés.
`error`	`str \| None`	Erreur terminale éventuelle.
`inbox_record`	`str \| None`	Chemin de l’enregistrement Inbox.
`rtk`	`dict`	Contexte temps réel associé.
`agents_used`	`list[str]`	Agents effectivement routés.
`mission_contract`	`dict \| None`	Contrat borné de la mission.
`mission_runtime`	`dict`	État synthétique du runtime.
`mission_intake`	`dict`	Brief, questions et identifiants Mission Intake.

ToolResult et ExecutionEnvelope

ToolResult

success, tool, result, error, evidence.

ExecutionEnvelope

version, intent, project_id, summary, selected_skills, complete, completion_summary, actions.

Sprint

Objet Pydantic renvoyé par les méthodes Sprint. Les helpers progress() et control_snapshot() calculent respectivement les compteurs de tâches et l’état de contrôle synthétique.

Groupe	Champs
Identité	`id, project_id, goal, status, mission_id`
Cadrage	`questions, clarifications, deliberation, scope, constraints, acceptance_criteria`
Plan	`tasks`
Approbation	`requires_po_approval, approved_by, approved_at, approval_revision`
Acceptation	`accepted_by, accepted_at, acceptance_comment, acceptance_override`
Contrôle	`pause_requested, cancel_requested, paused_at, control_revision, control_history`
Temps	`started_at, finished_at, created_at, updated_at`

États Sprint : draft, grilling, awaiting_po_approval, planned, running, paused, blocked, completed, failed, aborted.

SprintTask

Groupe	Champs
Identité et DAG	`id, title, objective, depends_on, agent, capabilities, acceptance_criteria`
Exécution	`status, mission_id, run_id, command_id, node_id, dispatch_attempts, execution_attempts`
Temps	`started_at, finished_at, duration_ms`
Résultat	`summary, evidence, metrics, error`
Contrôle humain	`comments, manual_blocked, blocked_by, blocked_at`

États de tâche : pending, running, completed, blocked, failed.

08

Événements et observabilité

Un callback synchrone, sans dépendance imposée.

EventSink = Callable[[dict[str, Any]], None]. Chaque payload contient au minimum une clé event.

def on_event(payload: dict) -> None:
    event = payload.get("event", "unknown")
    print(f"[{event}]", payload)

report = igris.missions.run(
    "Analyse le projet et exécute ses tests",
    "mon-projet",
    event_sink=on_event,
)

L’observabilité Sprint est best-effort : une erreur levée par le sink ne doit pas transformer un travail réussi en échec. Le sink Mission est appelé directement par le service.

09

Erreurs, garanties et limites

Ce que la façade promet — et ce qu’elle n’expose pas.

ValueError

Identifiant projet invalide, transition Sprint interdite, réponse de grilling au mauvais état ou plan incohérent.

FileNotFoundError

sprints.run() et sprints.answer() échouent si l’identifiant Sprint est inconnu.

Erreurs provider/runtime

Les erreurs de configuration, base de données, provider ou tool peuvent remonter directement ou être décrites dans RunReport.

API locale et synchrone

Cette façade Python n’est ni un client HTTP ni une API async. Le Control Plane REST est une surface distincte.

Parité Sprint 3.6.1

La CLI et le dashboard exposent pause, continuation, arrêt, retry, commentaires, blocage et acceptation. SprintAPI expose actuellement seulement create, answer, run, get et list. Il ne faut pas annoncer les autres opérations comme publiques dans le SDK.

10

Configuration et stockage

Le SDK utilise exactement le même runtime que la CLI.

from core.config import Settings
from core.sdk import Igris

settings = Settings.load("./workspace")
igris = Igris(settings=settings)

workspace/inbox/mission-intake/Briefs, questions et continuations.
workspace/inbox/sprints/Objets Sprint persistés en JSON.
workspace/inbox/runs/Miroir des événements d’exécution.
workspace/inbox/recovery/runs/États et points de restauration.
workspace/projects/Sources et livrables des projets.

Sources de cette page : core/sdk/__init__.py, core/sdk/client.py, core/contracts.py, core/sprint/models.py, core/sprint/engine.py et core/service.py.