arcane-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,415 @@
+import { AxiosInstance, AxiosError } from 'axios';
+
+interface ArcaneClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    maxRetries?: number;
+    timeout?: number;
+}
+declare class ArcaneClient {
+    private readonly http;
+    constructor(config: ArcaneClientConfig);
+    getHttp(): AxiosInstance;
+    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    handleError(err: unknown): never;
+}
+
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+}
+interface Prompt {
+    id: string;
+    name: string;
+    description: string | null;
+    metadata: Record<string, unknown> | null;
+    promotedVersionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PromptVersion {
+    id: string;
+    promptId: string;
+    promptName: string;
+    versionName: string | null;
+    description: string | null;
+    modelConfigurationId: string;
+    template: unknown;
+    templateType: string;
+    templateFormat: string;
+    invocationParameters: unknown;
+    tools: unknown | null;
+    responseFormat: unknown | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Entity {
+    id: string;
+    name: string;
+    description?: string;
+    type: string;
+    matchingAttributeName: string;
+    matchingPatternType: string;
+    matchingPattern?: string | null;
+    matchingValue?: string | null;
+    entityType: string;
+    entityHighlights?: Array<{
+        title: string;
+        key: string;
+        valueType: string;
+    }>;
+    messageMatching?: Record<string, unknown> | null;
+    iconId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface DatasourceListItem {
+    id: string;
+    name: string;
+    description: string;
+    type: string;
+    source: string;
+    isSearchByQueryEnabled: boolean;
+    isSearchByAttributesEnabled: boolean;
+    isGetAttributeNamesEnabled: boolean;
+    isGetAttributeValuesEnabled: boolean;
+}
+interface TraceSearchResponse {
+    traces: Array<{
+        traceID: string;
+        rootServiceName?: string;
+        rootTraceName?: string;
+        startTimeUnixNano?: string;
+        durationMs?: number;
+        spanSet?: {
+            spans?: unknown[];
+            matched?: number;
+        };
+    }>;
+}
+interface TraceResponse {
+    batches: unknown[];
+}
+interface DatasetListItem {
+    id: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface DatasetRow {
+    id: string;
+    values: string[];
+}
+interface Dataset {
+    id: string;
+    name: string;
+    description?: string;
+    header: string[];
+    rows: DatasetRow[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface PaginatedDataset {
+    id: string;
+    name: string;
+    description?: string;
+    header: string[];
+    data: DatasetRow[];
+    pagination: PaginationMeta;
+}
+interface Evaluation {
+    id: string;
+    projectId: string;
+    evaluationType: string;
+    evaluationScope: string;
+    name: string;
+    description?: string | null;
+    datasetId?: string | null;
+    metadata?: Record<string, unknown> | null;
+    scoreMappings?: Record<string, Record<string, unknown>> | null;
+    ragasModelConfigurationId?: string | null;
+    scores: Array<{
+        id: string;
+        description: string;
+        scoringType: string;
+    }>;
+    experiments: Array<{
+        id: string;
+        promptVersionId: string;
+        datasetId: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface EvaluationResult {
+    id: string;
+    datasetRowId?: string | null;
+    datasetRow?: DatasetRow | null;
+    experimentResultId?: string | null;
+    scoreResults: Array<{
+        id: string;
+        scoreId: string;
+        value: number | null;
+        reasoning?: string | null;
+        status: string;
+        datasetRowId?: string | null;
+    }>;
+    createdAt: string;
+}
+interface ExperimentScores {
+    experimentId: string;
+    evaluationId: string;
+    scoreResults: Array<{
+        id: string;
+        scoreId: string;
+        value: number | null;
+        reasoning?: string | null;
+        status: string;
+        datasetRowId?: string | null;
+    }>;
+    totalCount: number;
+}
+interface Experiment {
+    id: string;
+    projectId: string;
+    name: string;
+    description?: string | null;
+    promptVersionId: string;
+    datasetId: string;
+    promptInputMappings: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+    results?: ExperimentResult[];
+}
+interface ExperimentResult {
+    id: string;
+    datasetRowId: string;
+    result: string | null;
+    status: string;
+    createdAt: string;
+}
+interface CombinedExperimentResult {
+    datasetRow: DatasetRow;
+    experimentResult: string | null;
+    experimentResultId: string;
+    createdAt: string;
+}
+interface PaginatedExperimentResults {
+    data: CombinedExperimentResult[];
+    pagination: PaginationMeta;
+}
+interface SearchTracesParams {
+    minDuration?: number;
+    maxDuration?: number;
+    start?: string;
+    end?: string;
+    limit?: number;
+    q?: string;
+    serviceName?: string;
+    operationName?: string;
+    attributes?: string;
+    filterByAttributeExists?: string[];
+}
+interface PaginationParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+interface CreateEvaluationParams {
+    evaluationType: 'AUTOMATIC' | 'MANUAL';
+    evaluationScope: 'DATASET' | 'EXPERIMENT';
+    name: string;
+    description?: string;
+    scoreIds: string[];
+    datasetId?: string;
+    experimentIds?: string[];
+    metadata?: Record<string, unknown>;
+    scoreMappings?: Record<string, Record<string, unknown>>;
+    ragasModelConfigurationId?: string;
+}
+interface CreateEvaluationResultParams {
+    datasetRowId?: string;
+    experimentResultId?: string;
+    scoreResults: Array<{
+        scoreId: string;
+        value: number;
+        reasoning?: string;
+    }>;
+}
+interface CreateExperimentParams {
+    name: string;
+    description?: string | null;
+    promptVersionId: string;
+    datasetId: string;
+    promptInputMappings?: Record<string, string>;
+}
+interface CreateExperimentResultParams {
+    datasetRowId: string;
+    result: string;
+}
+interface AddDatasetRowParams {
+    values: string[];
+}
+interface PendingScoreResult {
+    id: string;
+    scoreId: string;
+    value: number | null;
+    reasoning?: string | null;
+    status: string;
+    datasetRowId?: string | null;
+    experimentResultId?: string | null;
+}
+interface PaginatedPendingScoreResults {
+    data: PendingScoreResult[];
+    pagination: PaginationMeta;
+}
+interface ListPendingScoreResultsOptions {
+    experimentId?: string;
+    page?: number;
+    limit?: number;
+}
+interface ImportScoreResultRow {
+    datasetRowId?: string;
+    experimentResultId?: string;
+    value: number;
+    reasoning?: string;
+}
+interface ImportScoreResultsResponse {
+    importedCount: number;
+}
+
+declare class PromptsResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<Prompt[]>;
+    get(promptIdentifier: string): Promise<Prompt>;
+    listVersions(promptIdentifier: string): Promise<PromptVersion[]>;
+    getLatestVersion(promptIdentifier: string): Promise<PromptVersion>;
+}
+
+declare class DatasourcesResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<DatasourceListItem[]>;
+}
+
+declare class TracesResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    search(datasourceId: string, params?: SearchTracesParams): Promise<TraceSearchResponse>;
+    get(datasourceId: string, traceId: string): Promise<TraceResponse>;
+    getAttributeNames(datasourceId: string): Promise<string[]>;
+    getAttributeValues(datasourceId: string, attributeName: string): Promise<string[]>;
+}
+
+declare class DatasetsResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<DatasetListItem[]>;
+    get(datasetId: string, params?: PaginationParams): Promise<PaginatedDataset>;
+    listRowsPaginated(datasetId: string, options?: {
+        pageSize?: number;
+    }): AsyncGenerator<DatasetRow, void, unknown>;
+    addRow(datasetId: string, params: AddDatasetRowParams): Promise<DatasetRow>;
+}
+
+declare class EntitiesResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<Entity[]>;
+    get(entityId: string): Promise<Entity>;
+}
+
+declare class EvaluationsResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<Evaluation[]>;
+    get(evaluationId: string): Promise<Evaluation>;
+    getExperimentScores(evaluationId: string, experimentId: string): Promise<ExperimentScores>;
+    create(params: CreateEvaluationParams): Promise<Evaluation>;
+    createResult(evaluationId: string, params: CreateEvaluationResultParams): Promise<EvaluationResult>;
+    listPendingScoreResults(evaluationId: string, scoreId: string, options?: ListPendingScoreResultsOptions): Promise<{
+        data: PendingScoreResult[];
+        pagination: {
+            page: number;
+            limit: number;
+            total: number;
+            totalPages: number;
+            hasNextPage: boolean;
+            hasPreviousPage: boolean;
+        };
+    }>;
+    listPendingScoreResultsIterator(evaluationId: string, scoreId: string, options?: Omit<ListPendingScoreResultsOptions, 'page'>): AsyncGenerator<PendingScoreResult>;
+    importScoreResults(evaluationId: string, scoreId: string, results: ImportScoreResultRow[]): Promise<ImportScoreResultsResponse>;
+}
+
+declare class ExperimentsResource {
+    private readonly client;
+    constructor(client: ArcaneClient);
+    list(): Promise<Experiment[]>;
+    get(experimentId: string): Promise<Experiment>;
+    listResults(experimentId: string, params?: PaginationParams): Promise<PaginatedExperimentResults>;
+    listResultsPaginated(experimentId: string, options?: {
+        pageSize?: number;
+    }): AsyncGenerator<CombinedExperimentResult, void, unknown>;
+    create(params: CreateExperimentParams): Promise<Experiment>;
+    createResult(experimentId: string, params: CreateExperimentResultParams): Promise<ExperimentResult>;
+}
+
+declare class ArcanApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly requestId?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, requestId?: string | undefined, cause?: unknown | undefined);
+    static fromAxiosError(err: AxiosError<{
+        message?: string;
+    }>): ArcanApiError;
+}
+declare class ArcanNotFoundError extends ArcanApiError {
+    constructor(message: string, requestId?: string);
+}
+declare class ArcanUnauthorizedError extends ArcanApiError {
+    constructor(message: string, requestId?: string);
+}
+
+/**
+ * High-level client for the Arcane public API.
+ * Use project-scoped API keys for authentication.
+ *
+ * @example
+ * ```ts
+ * import { Arcan } from 'arcane-sdk';
+ *
+ * const arcan = new Arcan({
+ *   baseUrl: 'https://api.example.com',
+ *   apiKey: process.env.ARCAN_API_KEY!,
+ * });
+ *
+ * const prompts = await arcan.prompts.list();
+ * const datasets = await arcan.datasets.list();
+ *
+ * for await (const result of arcan.experiments.listResultsPaginated('exp-id')) {
+ *   console.log(result);
+ * }
+ * ```
+ */
+declare class Arcan extends ArcaneClient {
+    readonly prompts: PromptsResource;
+    readonly datasources: DatasourcesResource;
+    readonly traces: TracesResource;
+    readonly datasets: DatasetsResource;
+    readonly entities: EntitiesResource;
+    readonly evaluations: EvaluationsResource;
+    readonly experiments: ExperimentsResource;
+    constructor(config: ArcaneClientConfig);
+}
+
+export { type AddDatasetRowParams, Arcan, ArcanApiError, ArcanNotFoundError, ArcanUnauthorizedError, ArcaneClient, type ArcaneClientConfig, type CombinedExperimentResult, type CreateEvaluationParams, type CreateEvaluationResultParams, type CreateExperimentParams, type CreateExperimentResultParams, type Dataset, type DatasetListItem, type DatasetRow, type DatasourceListItem, type Entity, type Evaluation, type EvaluationResult, type Experiment, type ExperimentResult, type ExperimentScores, type ImportScoreResultRow, type ImportScoreResultsResponse, type ListPendingScoreResultsOptions, type PaginatedDataset, type PaginatedExperimentResults, type PaginatedPendingScoreResults, type PaginationMeta, type PaginationParams, type PendingScoreResult, type Prompt, type PromptVersion, type SearchTracesParams, type TraceResponse, type TraceSearchResponse };