arcane-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023-2025 ArcaneTracing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# arcane-sdk
+
+Official TypeScript/JavaScript SDK for the Arcane public API.
+
+## Installation
+
+```bash
+npm install arcane-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Arcane } from 'arcane-sdk';
+
+const arcane = new Arcane({
+  baseUrl: 'https://your-instance.example.com',
+  apiKey: process.env.ARCAN_API_KEY!,
+});
+
+// List prompts
+const prompts = await arcane.prompts.list();
+
+// Get a dataset (paginated rows, default page 1)
+const dataset = await arcane.datasets.get('dataset-uuid', { page: 1, limit: 20 });
+
+// Iterate over all rows without loading everything
+for await (const row of arcane.datasets.listRowsPaginated('dataset-uuid')) {
+  console.log(row.values);
+}
+
+// Add a row
+const newRow = await arcane.datasets.addRow('dataset-uuid', {
+  values: ['input1', 'input2', 'expected'],
+});
+
+// Search traces
+const searchResult = await arcane.traces.search('datasource-uuid', {
+  limit: 100,
+  q: 'status_code=200',
+});
+
+// Iterate over experiment results (paginated, memory-efficient)
+for await (const result of arcane.experiments.listResultsPaginated('experiment-uuid')) {
+  console.log(result.datasetRow, result.experimentResult);
+}
+```
+
+## Authentication
+
+Use a **project-scoped API key**. Create one in the Arcane UI under Project → API Keys.
+
+The SDK uses HTTP Basic Auth with username `api-key` and the API key as the password.
+
+## Resources
+
+| Resource     | Methods                                                                 |
+| ------------ | ----------------------------------------------------------------------- |
+| `prompts`    | `list()`, `get(id)`, `listVersions(id)`, `getLatestVersion(id)`         |
+| `datasources`| `list()`                                                                |
+| `traces`     | `search(datasourceId, params)`, `get(datasourceId, traceId)`, `getAttributeNames()`, `getAttributeValues()` |
+| `datasets`   | `list()`, `get(id, params?)`, `listRowsPaginated(id)`, `addRow(id, { values })` |
+| `entities`   | `list()`, `get(id)`                                                             |
+| `evaluations`| `list()`, `get(id)`, `getExperimentScores()`, `create()`, `createResult()` |
+| `experiments`| `list()`, `get(id)`, `listResults()`, `listResultsPaginated()`, `create()`, `createResult()` |
+
+## Retries
+
+The SDK automatically retries on:
+
+- HTTP 5xx errors
+- Network errors (`ECONNRESET`, `ETIMEDOUT`)
+
+Configure with `maxRetries` (default: 3):
+
+```typescript
+const arcane = new Arcane({
+  baseUrl: 'https://api.example.com',
+  apiKey: '...',
+  maxRetries: 5,
+});
+```
+
+## Error Handling
+
+```typescript
+import { Arcane, ArcanApiError, ArcanNotFoundError } from 'arcane-sdk';
+
+try {
+  await arcane.datasets.get('invalid-id');
+} catch (err) {
+  if (err instanceof ArcanNotFoundError) {
+    console.log('Dataset not found');
+  } else if (err instanceof ArcanApiError) {
+    console.log(err.statusCode, err.message, err.requestId);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };