Agent de l'espace de travail

Posez des questions sur cet espace de travail ou prévisualisez des ajouts uniquement.

Organigram Agent

Primitives de l'agent d'espace de travail pour les applications Organigram.

Ce paquet contient les parties publiques et indépendantes de tout framework de l'agent d'espace de travail d'Organigram : types de requêtes et de réponses, construction de l'instantané et du prompt, normalisation des réponses, extraction de la consommation du modèle et extraction du texte des documents.

Installation


pnpm add @organigram/agent

Prompt

L'agent répond aux questions sur un espace de travail et prépare des modifications de ses organigrammes. Rassemblez ce que l'utilisateur peut voir de l'espace de travail dans un Context, et construisez le prompt avec buildPrompt(). Le prompt inclut un instantané de l'espace de travail, avec les noms des fichiers mais jamais leur contenu. Envoyez-le au modèle de langage de votre choix, avec WORKSPACE_AGENT_OUTPUT_SCHEMA comme format de sortie structurée quand le fournisseur le permet.

buildPrompt

Construire le prompt de l'agent d'espace de travail pour une conversation.

Le prompt contient les règles de l'agent, un instantané de l'espace de travail construit avec buildSnapshot(), la conversation et le schéma de sortie. Il interdit les propositions, transactions et signatures, et demande au modèle de traiter les noms de fichiers, les notifications et le contenu des documents comme des données et non comme des instructions. Il ne peut pas faire respecter ces règles : validez la réponse avec normalizeResponse().


const prompt = buildPrompt({ messages, context })
const answer = normalizeResponse(JSON.parse(completion), context)

Signature


buildPrompt: (input: {
    messages: Message[];
    context: Context;
}) => string

NEW_ORGANIGRAM_GENERATION_INSTRUCTIONS

Instructions pour générer un nouvel organigramme à partir d'une description ou de documents, comme des statuts, incluses dans le prompt de buildPrompt().

WORKSPACE_AGENT_OUTPUT_SCHEMA

Schéma JSON des réponses attendues du modèle de langage, à passer comme format de sortie structurée.

buildSnapshot

Construire la description d'un espace de travail donnée à l'agent dans son prompt.

L'instantané ne garde que les champs dont l'agent a besoin : l'espace de travail, ses organigrammes avec leurs organes, entrées, procédures, dernières propositions et scrutins, et actifs, plus les noms et références des fichiers et les notifications. Il ne contient jamais le contenu des fichiers. Il inclut generatedAt, la date de sa construction.

Signature


buildSnapshot: (context: Context) => Record<string, unknown>

Paramètres

Nom	Type	Description
`context`	`Context`	Ce que l'on sait de l'espace de travail.

MAX_PROPOSALS_PER_PROCEDURE

Nombre de dernières propositions de chaque procédure incluses dans un instantané.

Definition


const MAX_PROPOSALS_PER_PROCEDURE = 10

Context

Ce que l'agent sait d'un espace de travail : l'entrée de buildSnapshot(), buildPrompt() et normalizeResponse().

Definition


export type Context = {
    workspace: Workspace;
    files: File[];
    notifications: Notification[];
    currentOrganigram: OrganigramJson | null;
};

File

Un fichier de l'espace de travail. L'agent ne voit que sa référence et son nom, pas son contenu.

Definition


export type File = {
    cid: string;
    name?: string | null;
};

Notification

Une notification de l'espace de travail.

Definition


export type Notification = {
    id: string;
    type: string;
    title?: string | null;
    body?: string | null;
    href?: string | null;
    createdAt: Date | string;
};

Workspace

L'espace de travail sur lequel l'agent répond.

Definition


export type Workspace = {
    id: string;
    slug: string;
    name?: string | null;
    description?: string | null;
    admins: string[];
    ownerUserAddress?: string | null;
    ownerOrganizationId?: string | null;
    ownerOrganization?: {
        id?: string | null;
    } | null;
    organigrams: OrganigramInput[];
};

Réponses

La sortie d'un modèle de langage n'est pas fiable. normalizeResponse() ne garde que les citations valides, et seulement les aperçus qui créent un nouvel organigramme ou complètent un organigramme non déployé, sans modifier ce qu'il contient. L'agent ne propose, ne signe ni n'envoie jamais de transactions : un organigramme déployé ne change que par ses propres procédures.

normalizeResponse

Valider la réponse du modèle de langage et la transformer en AgentResponse.

Traitez la sortie du modèle comme non fiable. Sans message, la réponse est remplacée par un message de repli. Seules les citations de types connus sont gardées, 8 au plus. Un aperçu n'est gardé que s'il s'agit d'un nouvel organigramme, ou d'un ajout à un organigramme de l'espace de travail qui n'a aucun organe, procédure ou actif déployé et qui ne modifie ni ne retire aucun de ses organes, entrées, procédures ou actifs. Les aperçus invalides sont écartés.

Signature


normalizeResponse: (input: unknown, context: Context) => AgentResponse

Paramètres

Nom	Type	Description
`input`	`unknown`	La réponse du modèle, analysée depuis le JSON.
`context`	`Context`	Le contexte avec lequel le prompt a été construit.

Retourne

Type	Description
`AgentResponse`	La réponse, sans `threadId`.

AgentResponse

Une réponse de l'agent d'espace de travail, telle que renvoyée par normalizeResponse().

Definition


export type AgentResponse = {
    threadId?: string;
    message: string;
    citations: Citation[];
    preview?: OrganigramPreview;
};

Citation

Une référence à un objet de l'espace de travail qui étaye une réponse de l'agent.

Definition


export type Citation = {
    type: 'workspace' | 'organigram' | 'organ' | 'procedure' | 'asset' | 'notification' | 'file';
    id: string;
    label: string;
};

MergeOrganigramPreview

Un ajout proposé à un organigramme existant qui n'est pas encore déployé.

Definition


export type MergeOrganigramPreview = {
    type: 'organigram';
    organigramId: string;
    persistence: 'merge-additive';
    summary: string[];
    organigram: OrganigramJson;
};

NewOrganigramPreview

Un nouvel organigramme proposé.

Definition


export type NewOrganigramPreview = {
    type: 'new-organigram';
    persistence: 'create';
    summary: string[];
    organigram: OrganigramJson;
};

OrganigramPreview

Une modification d'organigrammes proposée par l'agent, que l'utilisateur examine avant de l'enregistrer.

Definition


export type OrganigramPreview = MergeOrganigramPreview | NewOrganigramPreview;

Conversations

Types des requêtes adressées à l'agent et des conversations stockées dans l'historique d'un espace de travail.

AgentRequest

Corps d'une requête à l'agent d'espace de travail.

Definition


export type AgentRequest = {
    threadId?: string | null;
    message?: string;
    messages?: Message[];
    currentOrganigramId?: string | null;
    source?: ThreadSource;
};

Message

Un message d'une conversation avec l'agent d'espace de travail.

Definition


export type Message = {
    role: 'user' | 'assistant';
    content: string;
};

RecordThreadRequest

Corps d'une requête qui enregistre dans l'historique de l'espace de travail une conversation tenue ailleurs, comme dans l'en-tête de la page d'accueil.

Definition


export type RecordThreadRequest = {
    action: 'recordThread';
    source: ThreadSource;
    userMessage: string;
    assistantMessage: string;
    currentOrganigramId?: string | null;
};

StoredMessage

Un message tel que stocké dans l'historique d'une conversation.

Definition


export type StoredMessage = Message & {
    id: string;
    createdAt: string;
    response?: AgentResponse;
};

Thread

Une conversation enregistrée avec l'agent d'espace de travail.

Definition


export type Thread = {
    id: string;
    title: string;
    source: ThreadSource;
    workspace?: ThreadWorkspace | null;
    currentOrganigramId?: string | null;
    createdAt: string;
    updatedAt: string;
    messages: StoredMessage[];
};

ThreadSource

Où une conversation a commencé : dans un espace de travail, ou dans l'en-tête de la page d'accueil.

Definition


export type ThreadSource = 'workspace' | 'hero';

ThreadsResponse

Liste des conversations d'un utilisateur.

Definition


export type ThreadsResponse = {
    threads: Thread[];
};

ThreadWorkspace

L'espace de travail d'une conversation.

Definition


export type ThreadWorkspace = {
    id: string;
    name?: string | null;
};

isMessage

Vérifier qu'une valeur est un message avec un rôle et un contenu non vide, par exemple dans le corps d'une requête.

Signature


isMessage: (value: unknown) => value is Message

Paramètres

Nom	Type	Description
`value`	`unknown`	La valeur à vérifier.

Documents

Les utilisateurs peuvent envoyer des statuts ou d'autres documents dont l'agent tire un organigramme. Ces fonctions extraient leur texte sur le serveur. Ce texte est écrit par des tiers : donnez-le au modèle comme donnée.

UploadedDocument

Un fichier envoyé par un utilisateur, sous forme de File.

Definition


export type UploadedDocument = Pick<File, 'name' | 'type' | 'arrayBuffer' | 'text'>;

extractTextFromUploadedDocument

Extraire le texte d'un document envoyé, pour le donner à l'agent.

Lit les documents Word (corps, en-têtes, pieds de page, notes de bas de page et de fin), les fichiers PDF et le texte brut. Les pages PDF sans assez de texte sont lues par OCR en anglais et en français, ce qui nécessite Poppler (pdftocairo) installé sur le serveur ; si l'OCR échoue, le texte trouvé dans le PDF est conservé. Fonctionne uniquement sous Node.js. Le texte est écrit par des tiers : donnez-le au modèle comme donnée, jamais comme instruction.

Signature


extractTextFromUploadedDocument: (file: UploadedDocument) => Promise<string>

Paramètres

Nom	Type	Description
`file`	`UploadedDocument`	Le fichier envoyé.

Retourne

Type	Description
`Promise<string>`	Le texte, avec les espaces normalisés.

isDocxDocument

Vérifier si un fichier est un document Word (.docx), d'après son type MIME ou son extension.

Signature


isDocxDocument: (file: Pick<UploadedDocument, "name" | "type">) => boolean

Paramètres

Nom	Type	Description
`file`	`Pick<UploadedDocument, "name" \| "type">`	Le fichier à vérifier.

isPdfDocument

Vérifier si un fichier est un PDF, d'après son type MIME ou son extension.

Signature


isPdfDocument: (file: Pick<UploadedDocument, "name" | "type">) => boolean

Paramètres

Nom	Type	Description
`file`	`Pick<UploadedDocument, "name" \| "type">`	Le fichier à vérifier.

Utilisation

Compter les jetons utilisés par chaque appel à un modèle de langage, pour facturer ou limiter l'usage.

extractModelUsage

Lire dans la réponse du fournisseur les jetons utilisés par un appel à un modèle de langage.

Lit les champs d'usage des réponses compatibles OpenAI (input_tokens, prompt_tokens, détails des jetons en cache) et des réponses Ollama (prompt_eval_count, eval_count). Quand le fournisseur n'indique pas de jetons d'entrée ou de sortie, ils sont estimés au quart de la longueur du prompt ou de la complétion, et estimatedTokens vaut true.

Signature


extractModelUsage: (input: {
    payload: unknown;
    prompt: string;
    completion: string;
    provider: string;
    model: string;
}) => AiModelUsage

AiModelUsage

Jetons utilisés par un appel à un modèle de langage.

Definition


export type AiModelUsage = {
    provider: string;
    model: string;
    inputTokens: number;
    cachedInputTokens: number;
    outputTokens: number;
    totalTokens: number;
    estimatedTokens: boolean;
};