Emrys-Merlin/agent-skills

Construire avec TypeSafe

TypeSafe rend les unités d'intelligence IA utilisables comme des primitives de programmation : de petits jugements que vous pouvez composer en capacités plus grandes. Ses modèles System One renvoient des jugements rapides et ciblés que le logiciel peut consommer directement. Jev est le modèle phare et le premier modèle System One de TypeSafe. Il comprend le langage naturel et renvoie des réponses typées et des probabilités plutôt que de générer du texte ou des explications de raisonnement. Le code possède le workflow ; le modèle fournit le bon sens programmable là où le code ordinaire a besoin de compréhension sémantique.

Appeler Jev via OpenRouter

Cette variante de la compétence appelle Jev via OpenRouter, et non via l'API propre de TypeSafe. La documentation de TypeSafe reste la référence pour les concepts et la conception des questions ; seuls l'accès, les identifiants de modèle et la facturation diffèrent.

• Identifiant : une clé API OpenRouter, facturée sur le compte OpenRouter. Aucun compte TypeSafe n'est nécessaire. Lisez-la depuis l'environnement (OPENROUTER_API_KEY, ou TYPESAFE_API_KEY définie sur la clé OpenRouter) ; ne la codez jamais en dur et conservez-la côté serveur dans les applications web.
• API System One (par défaut) : POST https://openrouter.ai/api/v1/systemone avec Authorization: Bearer <clé OpenRouter>. Elle implémente les formes de requête et de réponse de TypeSafe et ajoute id, provider et usage.cost à la réponse.
• SDK TypeSafe (@typesafe-ai/sdk, typesafe_sdk) : définissez l'URL de base sur https://openrouter.ai/api (le SDK ajoute /v1/systemone) via baseURL / base_url ou TYPESAFE_BASE_URL, et transmettez la clé OpenRouter via apiKey / api_key ou TYPESAFE_API_KEY. Tout le reste suit la documentation du SDK TypeSafe.
• N'appelez pas la liste des modèles du SDK (client.models.list()) : sur OpenRouter, elle atteint l'API Models d'OpenRouter, dont la forme de réponse est rejetée par le SDK.
• Identifiants de modèle : jev-1.14 (actuel), jev-1.13, ou jev-latest ; les identifiants nus correspondent à typesafe/jev-… et ~typesafe/jev-latest. Épinglez une version pour des seuils reproductibles. Consultez les modèles TypeSafe sur OpenRouter pour les versions actuelles, les prix et la longueur de contexte ; le champ model de la réponse nomme la version exacte qui a servi la requête.
• Box (localiser une cible décrite dans une image dans state) nécessite jev-1.14 ou ultérieur ; la version 1.13 la rejette avec une erreur 400. Box retourne toujours des bords, donc associez-la à un Noul lorsque la cible peut être absente.
• Surface alternative : l'API Decisions d'OpenRouter (POST https://openrouter.ai/api/alpha/decisions) et ses SDK TypeScript, Python et Go. Préférez-la uniquement lorsque le projet utilise déjà le SDK OpenRouter.
• Pas l'API typée de Jev : typesafe/jev-router est un routeur de chat-completions qui utilise Jev pour choisir un autre LLM. Il renvoie du texte généré, pas des réponses typées, donc il ne correspond pas aux modèles de cette compétence.
• Sessions cloud et sandboxées : la liste blanche réseau doit inclure openrouter.ai ; stockez la clé comme un secret, pas comme une variable d'environnement en clair.

Documentation OpenRouter : Jev sur OpenRouter, SDK TypeSafe sur OpenRouter, Tutoriel Jev, et l'index des docs (recherchez-y "Jev" pour trouver les cookbooks). Lorsque les documentations OpenRouter et TypeSafe divergent sur l'accès, les points de terminaison, les identifiants de modèle ou la tarification, la documentation OpenRouter prévaut pour cette configuration.

Lire la documentation en direct

La documentation en direct de TypeSafe est la source de vérité. Lisez-la dans le cadre de la tâche. Cette compétence donne une orientation ; la documentation contient les concepts actuels, les recommandations de formulation, les contrats API, l'utilisation du SDK, les modèles, les limites et des exemples concrets.

• Commencez par l'index de la documentation pour découvrir les pages et cookbooks pertinents. Utilisez des lectures ciblées plutôt que de charger l'intégralité du site.
• Mintlify sert le Markdown en ajoutant .md au chemin d'une page, par exemple comment construire avec TypeSafe. Suivez les liens depuis l'index ; convertissez les liens de pages de documentation sans extension en .md lorsque c'est utile. Résolvez les liens relatifs par rapport à https://docs.typesafe.ai.
• Avant d'écrire une intégration, lisez la page actuelle de l'API ou du SDK choisi et les recommandations de questions pertinentes pour la conception. Pour un nouveau workflow, inspectez également le cookbook le plus proche : il montre souvent une meilleure décomposition qu'un classificateur générique.
• Si l'index est indisponible, utilisez les liens directs ci-dessous ou la navigation du site. Si la récupération Markdown échoue, essayez la page normale. Si l'accès en direct est indisponible, utilisez la documentation locale disponible ou les types SDK installés, indiquez cette limitation et évitez d'inventer des détails dépendants de la version.

Tâche	Commencez ici ; suivez les détails pertinents
Comprendre le modèle de programmation	System One, guide de construction
Explorer quoi construire	Carte des cas d'usage, puis les cookbooks pertinents depuis l'index
Préparer les entrées et les questions	State, primitives, puis la page de la primitive choisie
Décider comment gérer l'incertitude	Confidence
Écrire du code API	SDK TypeSafe sur OpenRouter d'abord, puis API HTTP, SDK Python, ou SDK JavaScript pour les formes de requête, avec l'URL de base et la clé d'OpenRouter
Trouver des cookbooks OpenRouter	Blocage d'appels d'outils, cascade vérifiée, classification à grande échelle, approbation automatique des demandes de permission
Mettre à jour une intégration ancienne	Guide de migration et la référence actuelle du SDK installé

Trouver la forme utile

Partez du comportement souhaité par l'utilisateur : que doit montrer, sélectionner, modifier ou déléguer l'application ? Remontez aux jugements dont elle a besoin. Conservez les règles connues, les calculs, les recherches exactes et l'exécution dans le code. Préservez la pile et le périmètre choisis par l'utilisateur ; ajoutez TypeSafe là où la compréhension sémantique est utile.

Lors du brainstorming ou du choix d'une architecture, considérez plus que la classification. Les modèles ci-dessous sont des points de départ : combinez les primitives autour de l'objectif de l'utilisateur, y compris des idées qui ne correspondent pas à une recette établie.

• Router et remplir les arguments connus. Une requête peut sélectionner un gestionnaire et ses paramètres typés. Posez des questions utiles et spécifiques à chaque branche en amont et ne consommez que les réponses pertinentes. Explorez l'appel de fonction et le fan-out spéculatif.
• Sélectionner au lieu de générer. Trouvez des valeurs candidates ou des plages de source dans le code, utilisez un jugement pour sélectionner celle prévue, puis copiez-la ou normalisez-la. Le code peut également assembler le texte source dans un document formaté ou un guide de lecture. Explorez l'extraction de valeur et la récupération de structure.
• Trouver et juger des preuves. Récupérez des candidats, comparez leur pertinence par rapport à une requête et sélectionnez le contexte utile. Explorez le reclassement et la classification hiérarchique.
• Transformer les jugements en données réutilisables. Notez les dimensions une fois, puis laissez le code ou les contrôles utilisateur modifier les poids, seuils, classements et vues. Avec des résultats étiquetés, ces signaux peuvent devenir des caractéristiques ML classiques. Explorez le scoring composite et la découverte de caractéristiques.
• Vérifier et escalader. Vérifiez des affirmations ou des champs spécifiques par rapport à leurs preuves ; envoyez les cas incertains ou en échec à une personne ou à un modèle de raisonnement. Explorez les vérifications de citations et les cascades d'extraction.
• Répondre à un état changeant. Le code peut conserver les objectifs et les observations tandis que de nouveaux jugements guident la prochaine étape bornée. Gardez l'état inféré distinct des faits observés et vérifiez la fraîcheur avant d'appliquer un résultat à une situation modifiée.

Pour les demandes ouvertes, proposez les quelques directions qui servent le mieux l'objectif de l'utilisateur et recommandez un point de départ. Pour une demande concrète, choisissez le modèle pertinent et construisez ; un brainstorming n'est pas un détour obligatoire.

Concevoir les jugements

Choisissez en fonction de ce que signifie la réponse, puis lisez la page de primitive pertinente :

Besoin	Primitive	Distinction importante
Un élément d'un ensemble défini	Choice	Choisit une option ; sa distribution compare les options concurrentes
Si une condition est vraie	Noul	Probabilité de oui ; pas de confiance séparée ; utilisez-en un par étiquette lorsque plusieurs peuvent s'appliquer
Degré le long d'une dimension décrite	Score	Position pondérée par probabilité sur des niveaux ordonnés ; utilisez des Scores comparables par élément pour un classement gradué
Où se trouve une cible décrite dans une image	Box	Jev 1.14+ uniquement ; pas de critères ; retourne toujours les bords, donc demandez un Noul pour la présence

Donnez à chaque question suffisamment d'état pertinent pour répondre : texte source, identités, relations, politiques et faits actuels. Préférez les champs JSON nommés lorsque le contexte a plusieurs parties. Mettez le jugement dans les instructions et définissez ses réponses possibles dans les critères. Les identifiants de question sont destinés au code et ne sont pas envoyés au modèle ; incluez le sens complet dans la question. Référencez l'état imbriqué avec des chemins entre backticks comme ticket.messages[0].text.

Posez un jugement unique, étroit et cohérent par question. Séparez les dimensions indépendamment utiles, sans détruire la relation évaluée. Une sélection d'action bornée ou une interprétation contextuelle est valide ; atomique ne signifie pas extraction littérale de fait ou limite d'une phrase. Les chaînes fonctionnent pour les questions simples. Utilisez des objets ou tableaux structurés lorsque des définitions, des contrastes, des exclusions ou des exemples clarifient les instructions ou les critères. Les niveaux de Score doivent décrire des situations concrètes et se suffire à eux-mêmes.

Gardez les réponses nécessaires disponibles. Incluez un résultat « sans correspondance » lorsque rien ne correspond ; utilisez un jugement de présence séparé lorsqu'il est indépendamment utile. Pour la sélection de valeur source, vérifiez la couverture des candidats : le modèle ne peut pas choisir une valeur omise.

Composer et vérifier

Posez les questions indépendantes sur le même état ensemble, y compris les questions spéculatives utiles. Elles s'exécutent en parallèle et ne peuvent pas voir les réponses des unes des autres. Énoncez chaque prémisse spéculative explicitement ; le code consomme les réponses applicables. Une deuxième requête est justifiée lorsqu'une réponse antérieure est nécessaire pour récupérer des preuves, construire un nouvel état ou déterminer les options suivantes. Les questions supplémentaires utilisent toujours des tokens ; mesurez les budgets de requête réels, le coût et la latence de bout en bout.

Utilisez les probabilités et la confiance pour guider le comportement, avec des seuils évalués sur les données de l'utilisateur et les conséquences. La confiance Choice/Score résume la concentration de la distribution, pas l'exactitude globale du workflow ou l'autorisation d'agir. Un Noul proche de 0,5 signifie une probabilité similaire pour oui et non, pas une intensité moyenne. Plusieurs alternatives acceptables peuvent également répartir la probabilité ; une faible confiance n'invalide pas un choix de préférence inoffensif. Ignorez l'incertitude sur les branches inutilisées.

Gardez la politique explicite et les jugements bruts réutilisables. Les scores pondérés conviennent aux préférences compensatoires ; une règle « toute violation grave » nécessite des conditions séparées. Changer un poids ou un filtre d'affichage n'a pas besoin de relancer l'inférence lorsque les preuves et les significations des questions sont inchangées. La sortie typée garantit l'interface, pas la vérité. Les modèles System One sont entraînés pour des décisions calibrées ; validez leurs performances dans le domaine cible.

Testez des cas représentatifs et le comportement résultant de l'application. En cas d'échec, inspectez l'état exact, les questions, les candidats, les réponses, la composition et le résultat observé. Séparez les preuves manquantes, les erreurs de modèle, les erreurs de code et les échecs de service. Traitez les seuils des cookbooks et les résultats de démonstration comme des exemples à évaluer, pas comme des règles universelles ou des limitations permanentes du modèle. Conservez les identifiants API côté serveur dans les applications web.