@fastino-ai/pioneer-cli 0.2.5 → 0.2.6

package/src/api.ts

@@ -163,8 +163,12 @@ export interface Dataset {
   sample_size?: number;
   version_number?: string;
   root_dataset_id?: string;
+  project_id?: string;
   schema?: Record<string, unknown>;
   schema_warnings?: string[];
+  annotation_status?: "none" | "in_progress" | "completed";
+  annotation_config?: Record<string, unknown>;
+  annotation_progress?: Record<string, unknown>;
   created_at: string;
   updated_at?: string;
 }
@@ -209,6 +213,51 @@ export async function deleteDataset(dataset: DatasetRef): Promise<ApiResult> {
   return request("DELETE", `/felix/datasets/${dataset.name}/${dataset.version}`);
 }
 
+export async function deleteAllDatasetVersions(name: string): Promise<ApiResult> {
+  return request("DELETE", `/felix/datasets/${name}`);
+}
+
+export interface DatasetVersionsResponse {
+  success: boolean;
+  versions: Dataset[];
+  count: number;
+}
+
+export async function listDatasetVersions(
+  name: string
+): Promise<ApiResult<DatasetVersionsResponse>> {
+  return request<DatasetVersionsResponse>("GET", `/felix/datasets/${name}`);
+}
+
+export interface DatasetMetadataUpdate {
+  dataset_name?: string;
+  dataset_type?: "ner" | "classification" | "custom";
+  project_id?: string;
+}
+
+export async function updateDatasetMetadata(
+  dataset: DatasetRef,
+  update: DatasetMetadataUpdate
+): Promise<ApiResult<Dataset>> {
+  return request<Dataset>(
+    "PATCH",
+    `/felix/datasets/${dataset.name}/${dataset.version}`,
+    update
+  );
+}
+
+export async function previewDataset(
+  dataset: DatasetRef,
+  options: { limit?: number; offset?: number } = {}
+): Promise<ApiResult<Record<string, unknown>>> {
+  const params = new URLSearchParams();
+  if (options.limit) params.set("limit", String(options.limit));
+  if (options.offset) params.set("offset", String(options.offset));
+  const query = params.toString();
+  const url = `/felix/datasets/${dataset.name}/${dataset.version}/preview${query ? `?${query}` : ""}`;
+  return request<Record<string, unknown>>("GET", url);
+}
+
 export interface DatasetUploadRequest {
   dataset_name: string;
   dataset_type?: "ner" | "classification" | "custom";
@@ -366,9 +415,95 @@ export interface DatasetAnalysisRequest {
   analyses: string[];
 }
 
+// Diversity Analysis Types
+export interface DiversityPoint {
+  x?: number;
+  y?: number;
+  z?: number;
+  w?: number;
+  coordinates: number[];
+  text?: string;
+  token_count?: number;
+  labels?: string[];
+  metadata?: Record<string, unknown>;
+  sample_index?: number;
+  similarity_to_centroid?: number;
+  embedding?: number[];
+}
+
+export interface DiversityVisualization {
+  method: "pca" | "tsne";
+  dimensions: number;
+  points: DiversityPoint[];
+  tsne_perplexity?: number;
+  similarity_range?: { min: number; max: number };
+  token_count_range?: { min: number; max: number };
+}
+
+export interface DiversityLLMAnalysis {
+  reasoning_trace: string;
+  summary: string;
+  diversity_rating: "low" | "moderate" | "high" | "excellent";
+  key_observations: string[];
+  recommendations: string[];
+  model_used: string;
+}
+
+export interface DiversityAnalysis {
+  vendi_score: number;
+  sample_size: number;
+  interpretation?: string;
+  visualization?: DiversityVisualization;
+  llm_analysis?: DiversityLLMAnalysis;
+}
+
+// Distribution Analysis Types
+export interface DistributionAnalysis {
+  label_counts: Record<string, number>;
+  total_samples: number;
+  unique_labels: number;
+  most_common_label?: string;
+  least_common_label?: string;
+  imbalance_ratio?: number;
+}
+
+// Duplicates Analysis Types
+export interface DuplicatesAnalysis {
+  total_duplicates: number;
+  duplicate_groups: number;
+  duplicate_percentage: number;
+  examples?: Array<{ text: string; count: number }>;
+}
+
+// Outliers Analysis Types
+export interface OutliersAnalysis {
+  total_outliers: number;
+  outlier_percentage: number;
+  method: string;
+  threshold?: number;
+  examples?: Array<{ text: string; score: number; reason?: string }>;
+}
+
+// Splits Analysis Types
+export interface SplitsAnalysis {
+  train_size: number;
+  validation_size: number;
+  test_size?: number;
+  train_percentage: number;
+  validation_percentage: number;
+  test_percentage?: number;
+}
+
 export interface DatasetAnalysisResponse {
-  success: boolean;
-  analysis: unknown;
+  summary: Record<string, unknown>;
+  distribution?: DistributionAnalysis;
+  duplicates?: DuplicatesAnalysis;
+  outliers?: OutliersAnalysis;
+  correlations?: Record<string, unknown>;
+  splits?: SplitsAnalysis;
+  errors?: Record<string, unknown>;
+  diversity?: DiversityAnalysis;
+  natural_language_response?: string;
 }
 
 export async function analyzeDataset(
@@ -430,10 +565,13 @@ export interface GenerateNERRequest {
   num_examples?: number;
   domain_description?: string;
   seed?: number;
+  session_id?: string;
+  config_num_examples?: number;
   temperature?: number;
   constraints?: ConstraintRequest[];
   save_dataset?: boolean;
   dataset_name?: string;
+  project_id?: string;
 }
 
 export async function generateNER(
@@ -476,12 +614,15 @@ export interface GenerateClassificationRequest {
   domain_description?: string;
   seed?: number;
   class_balance?: Record<string, number>;
+  session_id?: string;
+  config_num_examples?: number;
   temperature?: number;
   batch_size?: number;
   constraints?: ConstraintRequest[];
   multi_label?: boolean;
   save_dataset?: boolean;
   dataset_name?: string;
+  project_id?: string;
 }
 
 export async function generateClassification(
@@ -523,14 +664,17 @@ export async function inferClassificationLabels(
 // Custom Generation
 export interface GenerateCustomRequest {
   prompt: string;
-  output_format: Record<string, unknown>;
+  output_format?: Record<string, unknown>;
+  infer_output_format?: boolean;
   num_examples?: number;
   seed?: number;
+  session_id?: string;
   min_criteria?: number;
   temperature?: number;
   constraints?: ConstraintRequest[];
   save_dataset?: boolean;
   dataset_name?: string;
+  project_id?: string;
 }
 
 export async function generateCustom(
@@ -610,8 +754,7 @@ export interface TrainingJob {
   id: string;
   user_id: string;
   model_name?: string;
-  dataset_ids: string[];
-  train_dataset_paths: string[];
+  datasets: Array<{ name: string; version?: string }>;
   base_model: string;
   validation_data_percentage: number;
   nr_epochs: number;
@@ -619,12 +762,16 @@ export interface TrainingJob {
   batch_size: number;
   trained_model_path?: string;
   job_reference?: string;
+  instance_type?: string;
   status: string;
   error_message?: string;
   created_at: string;
   updated_at: string;
   started_at?: string;
   completed_at?: string;
+  model_auto_selected?: boolean;
+  model_selection_reason?: string;
+  metrics?: Record<string, unknown>;
 }
 
 export interface TrainingJobListResponse {
@@ -633,8 +780,14 @@ export interface TrainingJobListResponse {
   count: number;
 }
 
-export async function listJobs(): Promise<ApiResult<TrainingJobListResponse>> {
-  return request<TrainingJobListResponse>("GET", "/felix/training-jobs");
+export async function listJobs(
+  options: { status?: string } = {}
+): Promise<ApiResult<TrainingJobListResponse>> {
+  const params = new URLSearchParams();
+  if (options.status) params.set("status", options.status);
+  const query = params.toString();
+  const url = query ? `/felix/training-jobs?${query}` : "/felix/training-jobs";
+  return request<TrainingJobListResponse>("GET", url);
 }
 
 export async function getJob(jobId: string): Promise<ApiResult<TrainingJob>> {
@@ -645,10 +798,20 @@ export interface TrainingJobCreateRequest {
   model_name: string;
   datasets: DatasetRef[];
   base_model?: string;
+  auto_select_model?: boolean;
   validation_data_percentage?: number;
   nr_epochs?: number;
   learning_rate?: number;
   batch_size?: number;
+  save_steps?: number;
+  wandb_api_key?: string;
+  project_id?: string;
+  training_type?: "full" | "lora";
+  lora_r?: number;
+  lora_alpha?: number;
+  lora_dropout?: number;
+  enable_probe_override?: boolean;
+  probe_delta_threshold?: number;
 }
 
 export async function createJob(
@@ -661,15 +824,15 @@ export interface TrainingLog {
   id: string;
   job_id: string;
   timestamp: string;
-  level: "INFO" | "WARNING" | "ERROR" | "DEBUG";
+  level: string;
   message: string;
-  source: "stdout" | "stderr";
+  source: string;
 }
 
 export interface TrainingLogsResponse {
-  success: boolean;
+  job_id: string;
   logs: TrainingLog[];
-  count: number;
+  total_logs: number;
 }
 
 export async function getJobLogs(
@@ -682,6 +845,103 @@ export async function deleteJob(jobId: string): Promise<ApiResult> {
   return request("DELETE", `/felix/training-jobs/${jobId}`);
 }
 
+export interface StopJobResponse {
+  success: boolean;
+  message: string;
+  job_id: string;
+  status: string;
+}
+
+export async function stopJob(
+  jobId: string
+): Promise<ApiResult<StopJobResponse>> {
+  return request<StopJobResponse>("POST", `/felix/training-jobs/${jobId}/stop`);
+}
+
+export interface TerminateJobResponse {
+  success: boolean;
+  message: string;
+  job_id: string;
+  deleted_checkpoints: number;
+}
+
+export async function terminateJob(
+  jobId: string
+): Promise<ApiResult<TerminateJobResponse>> {
+  return request<TerminateJobResponse>(
+    "POST",
+    `/felix/training-jobs/${jobId}/terminate`
+  );
+}
+
+export async function syncJob(jobId: string): Promise<ApiResult<TrainingJob>> {
+  return request<TrainingJob>("POST", `/felix/training-jobs/${jobId}/sync`);
+}
+
+export interface Checkpoint {
+  id: string;
+  job_id: string;
+  epoch: number;
+  step?: number;
+  training_loss?: number;
+  validation_loss?: number;
+  accuracy?: number;
+  learning_rate?: number;
+  gpu_memory_used?: number;
+  gpu_memory_total?: number;
+}
+
+export interface CheckpointListResponse {
+  success: boolean;
+  checkpoints: Checkpoint[];
+  count: number;
+}
+
+export async function listCheckpoints(
+  jobId: string
+): Promise<ApiResult<CheckpointListResponse>> {
+  return request<CheckpointListResponse>(
+    "GET",
+    `/felix/training-jobs/${jobId}/checkpoints`
+  );
+}
+
+export interface DeployCheckpointResponse {
+  success: boolean;
+  message: string;
+  job_id: string;
+  checkpoint_id: string;
+  mme_path: string;
+}
+
+export async function deployCheckpoint(
+  jobId: string,
+  checkpointId: string
+): Promise<ApiResult<DeployCheckpointResponse>> {
+  return request<DeployCheckpointResponse>(
+    "POST",
+    `/felix/training-jobs/${jobId}/checkpoints/${checkpointId}/deploy`
+  );
+}
+
+export interface UpdateModelNameResponse {
+  success: boolean;
+  message: string;
+  job_id: string;
+  model_name: string;
+}
+
+export async function updateModelName(
+  jobId: string,
+  modelName: string
+): Promise<ApiResult<UpdateModelNameResponse>> {
+  return request<UpdateModelNameResponse>(
+    "PATCH",
+    `/felix/training-jobs/${jobId}/model-name`,
+    { model_name: modelName }
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Models
 // ─────────────────────────────────────────────────────────────────────────────
@@ -707,8 +967,16 @@ export interface DeployedModelsListResponse {
   count: number;
 }
 
-export async function listModels(): Promise<ApiResult<DeployedModelsListResponse>> {
-  return request<DeployedModelsListResponse>("GET", "/felix/models");
+export async function listModels(
+  options: { includeBase?: boolean } = {}
+): Promise<ApiResult<DeployedModelsListResponse>> {
+  const params = new URLSearchParams();
+  if (options.includeBase !== undefined) {
+    params.set("include_base", String(options.includeBase));
+  }
+  const query = params.toString();
+  const url = query ? `/felix/models?${query}` : "/felix/models";
+  return request<DeployedModelsListResponse>("GET", url);
 }
 
 export async function deleteModel(jobId: string): Promise<ApiResult> {
@@ -810,13 +1078,41 @@ export async function downloadModel(
 export interface Evaluation {
   id: string;
   user_id: string;
-  dataset_id: string;
-  model_id?: string;
+  project_id?: string;
+  model_id: string;
+  dataset_name: string;
+  dataset_version: string;
+  provider?: string;
+  model_name?: string;
+  f1_score?: number;
+  precision_score?: number;
+  recall_score?: number;
+  accuracy?: number;
+  validation_loss?: number;
+  total_tokens?: number;
+  total_cost_usd?: number;
+  total_latency_ms?: number;
+  max_examples?: number;
+  seed?: number;
+  sample_count?: number;
+  evaluation_time_ms?: number;
   status: string;
-  results?: unknown;
+  job_reference?: string;
+  error_message?: string;
   created_at: string;
   completed_at?: string;
-  predictions?: Array<Record<string, unknown>>;
+}
+
+export interface EvaluationListResponse {
+  success: boolean;
+  evaluations: Evaluation[];
+  count: number;
+}
+
+export async function listEvaluations(): Promise<
+  ApiResult<EvaluationListResponse>
+> {
+  return request<EvaluationListResponse>("GET", "/felix/evaluations");
 }
 
 export async function getEvaluation(
@@ -828,16 +1124,27 @@ export async function getEvaluation(
 export interface EvaluationCreateRequest {
   dataset: DatasetRef;
   model_id: string;
+  dataset_names?: string[];
+  provider?: "felix" | "openai" | "together";
+  max_examples?: number;
+  seed?: number;
   task_type?: string;
   text_column?: string;
   label_column?: string;
+  project_id?: string;
+}
+
+export interface EvaluationCreateResponse {
+  success: boolean;
+  evaluations: Evaluation[];
+  count: number;
 }
 
 export async function createEvaluation(
   req: EvaluationCreateRequest
-): Promise<ApiResult<Evaluation>> {
+): Promise<ApiResult<EvaluationCreateResponse>> {
   const { dataset, ...rest } = req;
-  return request<Evaluation>("POST", "/felix/evaluations", {
+  return request<EvaluationCreateResponse>("POST", "/felix/evaluations", {
     ...rest,
     dataset_name: dataset.name,
     dataset_version: dataset.version,
@@ -853,8 +1160,8 @@ export interface ModelWithEvaluation {
 
 export interface DatasetEvaluationsResponse {
   success: boolean;
-  dataset_id: string;
   dataset_name: string;
+  dataset_version: string;
   sample_count: number;
   models: ModelWithEvaluation[];
   count: number;
@@ -1088,13 +1395,15 @@ export interface HuggingFacePushRequest {
   hf_token: string;
   repo_id: string;
   private?: boolean;
+  commit_message?: string;
 }
 
 export interface HuggingFacePushResponse {
   success: boolean;
-  repo_url: string;
+  url: string;
   repo_id: string;
-  message?: string;
+  version: string;
+  message: string;
 }
 
 export async function pushDatasetToHub(
@@ -1112,13 +1421,15 @@ export interface HuggingFacePushModelRequest {
   hf_token: string;
   repo_id: string;
   private?: boolean;
+  commit_message?: string;
 }
 
 export interface HuggingFacePushModelResponse {
   success: boolean;
-  repo_url: string;
+  url: string;
   repo_id: string;
-  message?: string;
+  job_id: string;
+  message: string;
 }
 
 export async function pushModelToHub(
@@ -1133,26 +1444,525 @@ export async function pushModelToHub(
 }
 
 export interface HuggingFacePullRequest {
-  hf_token?: string;
   repo_id: string;
-  dataset_name?: string;
+  hf_token: string;
   revision?: string;
+  name?: string;
+}
+
+export async function pullDatasetFromHub(
+  options: HuggingFacePullRequest
+): Promise<ApiResult<Dataset>> {
+  return request<Dataset>(
+    "POST",
+    "/felix/datasets/pull-from-hub",
+    options
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constraints Generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GenerateNERConstraintsRequest {
+  labels: string[];
+  domain_description?: string;
+  min_criteria?: number;
+}
+
+export interface GenerateClassificationConstraintsRequest {
+  labels: string[];
+  domain_description?: string;
+  min_criteria?: number;
+}
+
+export interface GenerateRecordsConstraintsRequest {
+  fields: RecordField[];
+  domain_description?: string;
+  min_criteria?: number;
+}
+
+export interface GenerateConstraintsResponse {
+  success: boolean;
+  constraints: ConstraintRequest[];
+  count: number;
+  token_usage?: number;
+}
+
+export async function generateNERConstraints(
+  req: GenerateNERConstraintsRequest
+): Promise<ApiResult<GenerateConstraintsResponse>> {
+  return request<GenerateConstraintsResponse>(
+    "POST",
+    "/felix/constraints/ner",
+    req
+  );
+}
+
+export async function generateClassificationConstraints(
+  req: GenerateClassificationConstraintsRequest
+): Promise<ApiResult<GenerateConstraintsResponse>> {
+  return request<GenerateConstraintsResponse>(
+    "POST",
+    "/felix/constraints/classification",
+    req
+  );
+}
+
+export async function generateRecordsConstraints(
+  req: GenerateRecordsConstraintsRequest
+): Promise<ApiResult<GenerateConstraintsResponse>> {
+  return request<GenerateConstraintsResponse>(
+    "POST",
+    "/felix/constraints/records",
+    req
+  );
+}
+
+export interface ExpandConstraintChoicesRequest {
+  constraint: ConstraintRequest;
+  task_description: string;
+  max_count?: number;
+}
+
+export interface ExpandConstraintChoicesResponse {
+  success: boolean;
+  constraint: ConstraintRequest;
+  expanded_choices: string[];
+  count: number;
+  token_usage?: number;
+}
+
+export async function expandConstraintChoices(
+  req: ExpandConstraintChoicesRequest
+): Promise<ApiResult<ExpandConstraintChoicesResponse>> {
+  return request<ExpandConstraintChoicesResponse>(
+    "POST",
+    "/felix/constraints/expand",
+    req
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dataset Augmentation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AugmentationOperation {
+  type: "remove_duplicates" | "remove_outliers" | "balance";
+  enabled: boolean;
+}
+
+export interface DatasetAugmentationRequest {
+  task_type: "ner" | "classification";
+  operations: AugmentationOperation[];
+  new_dataset_name: string;
+  dataset_name?: string;
+  dataset_version?: string;
+  dataset?: Record<string, unknown>[];
+  target_distribution?: Record<string, number>;
+  domain_description?: string;
+  labels?: string[];
 }
 
-export interface HuggingFacePullResponse {
+export interface DatasetAugmentationResponse {
   success: boolean;
+  original_dataset_name?: string;
+  original_dataset_version?: string;
+  new_dataset: Dataset;
+  modifications: Record<string, unknown>;
+  distribution_comparison: Record<string, unknown>[];
+  message: string;
+}
+
+export async function augmentDataset(
+  req: DatasetAugmentationRequest
+): Promise<ApiResult<DatasetAugmentationResponse>> {
+  return request<DatasetAugmentationResponse>(
+    "POST",
+    "/felix/dataset/augment",
+    req
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dataset Query
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface DatasetQueryRequest {
+  dataset_name: string;
+  code: string;
+  version?: string;
+  timeout?: number;
+  max_rows_returned?: number;
+}
+
+export interface DatasetQueryResponse {
+  success: boolean;
+  dataset_name: string;
+  dataset_version: string;
+  result: unknown;
+  result_type: "dataframe" | "series" | "scalar" | "string" | "none";
+  row_count?: number;
+  columns?: string[];
+  execution_time_ms: number;
+  truncated: boolean;
+  message: string;
+}
+
+export async function queryDataset(
+  req: DatasetQueryRequest
+): Promise<ApiResult<DatasetQueryResponse>> {
+  return request<DatasetQueryResponse>("POST", "/felix/dataset/query", req);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dataset Grow
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GrowDatasetRequest {
+  dataset_id: string;
+  new_dataset_name: string;
+  target_size: number;
+  class_balance?: boolean;
+  domain_description?: string;
+  temperature?: number;
+  session_id?: string;
+}
+
+export interface GrowDatasetResponse {
+  success: boolean;
+  dataset: Record<string, unknown>;
+  original_size: number;
+  new_size: number;
+  generated_count: number;
+  distribution: Record<string, number>;
+  token_usage?: number;
+}
+
+export async function growDataset(
+  req: GrowDatasetRequest
+): Promise<ApiResult<GrowDatasetResponse>> {
+  return request<GrowDatasetResponse>("POST", "/felix/dataset/grow", req);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Embeddings
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface EmbeddingsRequest {
+  text: string;
+  model?: string;
+}
+
+export interface EmbeddingsResponse {
+  embedding: number[];
+}
+
+export async function createEmbeddings(
+  req: EmbeddingsRequest
+): Promise<ApiResult<EmbeddingsResponse>> {
+  return request<EmbeddingsResponse>("POST", "/felix/embeddings", req);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Activity
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ActivityEvent {
+  id: string;
+  type: "project" | "dataset" | "model" | "evaluation" | "notebook" | "deployment";
+  name: string;
+  item_id: string;
+  created_by: string;
+  created_at: string;
+  project_id?: string;
+}
+
+export interface ActivityLogResponse {
+  success: boolean;
+  events?: ActivityEvent[];
+  count: number;
+}
+
+export async function listActivity(
+  options: { limit?: number } = {}
+): Promise<ApiResult<ActivityLogResponse>> {
+  const params = new URLSearchParams();
+  if (options.limit) params.set("limit", String(options.limit));
+  const query = params.toString();
+  const url = query ? `/felix/activity?${query}` : "/felix/activity";
+  return request<ActivityLogResponse>("GET", url);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Presets
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PresetMetadata {
+  id: string;
+  name: string;
+  description: string;
+  task_type: string;
+  tags?: string[];
+}
+
+export interface PresetDetail {
+  id: string;
+  name: string;
+  description: string;
+  task_type: string;
+  config: Record<string, unknown>;
+  tags?: string[];
+}
+
+export async function listPresets(): Promise<ApiResult<PresetMetadata[]>> {
+  return request<PresetMetadata[]>("GET", "/felix/presets");
+}
+
+export async function getPreset(
+  presetId: string
+): Promise<ApiResult<PresetDetail>> {
+  return request<PresetDetail>("GET", `/felix/presets/${presetId}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adaptive Annotation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface StartAnnotationSessionRequest {
+  column_name: string;
+  input_columns: string[];
+  task_description: string;
+  task_type?: "classification" | "scoring" | "entity_extraction" | "json_extraction";
+  output_dataset_name?: string;
+  possible_labels?: Array<{ name: string; description?: string }>;
+  scoring_criteria?: Array<Record<string, unknown>>;
+  entity_types?: Array<{ name: string; description?: string }>;
+  json_schema?: Array<Record<string, unknown>>;
+  auto_accept_threshold?: number;
+}
+
+export interface StartAnnotationSessionResponse {
+  success: boolean;
+  session_id: string;
+  dataset_id: string;
+  task_type: string;
+  total_items: number;
+}
+
+export async function startAnnotationSession(
+  datasetId: string,
+  req: StartAnnotationSessionRequest
+): Promise<ApiResult<StartAnnotationSessionResponse>> {
+  return request<StartAnnotationSessionResponse>(
+    "POST",
+    `/felix/datasets/annotate/${datasetId}/start`,
+    req
+  );
+}
+
+export interface NextAnnotationItemResponse {
+  complete: boolean;
+  rate_limited?: boolean;
+  auto_accepted_in_call?: number;
+  item_id?: number;
+  item_data?: Record<string, unknown>;
+  task_type?: string;
+  task_description?: string;
+  possible_labels?: string[];
+  scoring_criteria?: Array<Record<string, unknown>>;
+  entity_types?: Array<Record<string, unknown>>;
+  json_schema?: Array<Record<string, unknown>>;
+  suggestion?: Record<string, unknown>;
+  stats?: Record<string, unknown>;
+}
+
+export async function getNextAnnotationItem(
+  datasetId: string,
+  options: { maxAutoAccept?: number } = {}
+): Promise<ApiResult<NextAnnotationItemResponse>> {
+  const params = new URLSearchParams();
+  if (options.maxAutoAccept !== undefined) {
+    params.set("max_auto_accept", String(options.maxAutoAccept));
+  }
+  const query = params.toString();
+  const url = `/felix/datasets/annotate/${datasetId}/next${query ? `?${query}` : ""}`;
+  return request<NextAnnotationItemResponse>("GET", url);
+}
+
+export interface AnnotationFeedbackRequest {
+  item_id: number;
+  thumb: "up" | "down";
+  corrected_label?: string;
+  corrected_criteria?: Record<string, string>;
+  corrected_entities?: string[][];
+  corrected_json?: Record<string, unknown>;
+}
+
+export interface AnnotationFeedbackResponse {
+  success: boolean;
+  item_id: number;
+  action: "up" | "down";
+  was_correct: boolean;
+  similar_items_queued?: number;
+  stats?: Record<string, unknown>;
+}
+
+export async function submitAnnotationFeedback(
+  datasetId: string,
+  req: AnnotationFeedbackRequest
+): Promise<ApiResult<AnnotationFeedbackResponse>> {
+  return request<AnnotationFeedbackResponse>(
+    "POST",
+    `/felix/datasets/annotate/${datasetId}/feedback`,
+    req
+  );
+}
+
+export interface AnnotationStatsResponse {
+  total_items: number;
+  annotated: number;
+  remaining: number;
+  auto_accepted: number;
+  human_annotated: number;
+  auto_accept_rate: number;
+  label_stats?: Record<string, unknown>;
+}
+
+export async function getAnnotationStats(
+  datasetId: string
+): Promise<ApiResult<AnnotationStatsResponse>> {
+  return request<AnnotationStatsResponse>(
+    "GET",
+    `/felix/datasets/annotate/${datasetId}/stats`
+  );
+}
+
+export interface AnnotationDownloadResponse {
+  data: Record<string, unknown>[];
+  columns: string[];
+  rows: number;
+  stats?: AnnotationStatsResponse;
+}
+
+export async function downloadAnnotatedData(
+  datasetId: string
+): Promise<ApiResult<AnnotationDownloadResponse>> {
+  return request<AnnotationDownloadResponse>(
+    "GET",
+    `/felix/datasets/annotate/${datasetId}/download`
+  );
+}
+
+export interface EndAnnotationSessionResponse {
+  success: boolean;
+  message: string;
+  final_stats?: AnnotationStatsResponse;
+}
+
+export async function endAnnotationSession(
+  datasetId: string
+): Promise<ApiResult<EndAnnotationSessionResponse>> {
+  return request<EndAnnotationSessionResponse>(
+    "DELETE",
+    `/felix/datasets/annotate/${datasetId}/session`
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Leaderboard / Competitions
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LeaderboardEntry {
+  id: string;
+  dataset_id: string;
+  evaluation_id: string;
+  user_id: string;
+  display_name: string;
+  model_name: string;
+  model_id?: string;
+  f1_score: number;
+  precision_score?: number;
+  recall_score?: number;
+  accuracy?: number;
+  created_at: string;
+  updated_at: string;
+  rank?: number;
+}
+
+export interface CompetitionInfo {
   dataset_id: string;
   dataset_name: string;
-  sample_count: number;
-  message?: string;
+  dataset_type: string;
+  description?: string;
+  sample_count?: number;
+  labels?: string[];
+  sample_rows?: Record<string, unknown>[];
+  winner?: LeaderboardEntry;
+  total_entries: number;
 }
 
-export async function pullDatasetFromHub(
-  options: HuggingFacePullRequest
-): Promise<ApiResult<HuggingFacePullResponse>> {
-  return request<HuggingFacePullResponse>(
+export interface CompetitionsResponse {
+  success: boolean;
+  competitions: CompetitionInfo[];
+}
+
+export interface CompetitionSamplesResponse {
+  dataset_id: string;
+  sample_rows: Record<string, unknown>[];
+}
+
+export interface LeaderboardEntriesResponse {
+  success: boolean;
+  dataset_id: string;
+  dataset_name: string;
+  entries: LeaderboardEntry[];
+  total_entries: number;
+}
+
+export interface LeaderboardSubmission {
+  evaluation_id: string;
+  display_name: string;
+}
+
+export interface LeaderboardSubmitResponse {
+  success: boolean;
+  entry: LeaderboardEntry;
+  rank: number;
+  is_new_best: boolean;
+}
+
+export async function listCompetitions(): Promise<ApiResult<CompetitionsResponse>> {
+  return request<CompetitionsResponse>("GET", "/leaderboard/competitions");
+}
+
+export async function getCompetitionSamples(
+  datasetId: string
+): Promise<ApiResult<CompetitionSamplesResponse>> {
+  return request<CompetitionSamplesResponse>(
+    "GET",
+    `/leaderboard/competitions/${datasetId}/samples`
+  );
+}
+
+export async function getLeaderboardEntries(
+  datasetId: string,
+  limit?: number
+): Promise<ApiResult<LeaderboardEntriesResponse>> {
+  const params = new URLSearchParams();
+  if (limit) params.set("limit", String(limit));
+  const query = params.toString();
+  const url = `/leaderboard/datasets/${datasetId}/entries${query ? `?${query}` : ""}`;
+  return request<LeaderboardEntriesResponse>("GET", url);
+}
+
+export async function submitToLeaderboard(
+  datasetId: string,
+  submission: LeaderboardSubmission
+): Promise<ApiResult<LeaderboardSubmitResponse>> {
+  return request<LeaderboardSubmitResponse>(
     "POST",
-    "/felix/datasets/pull-from-hub",
-    options
+    `/leaderboard/datasets/${datasetId}/submit`,
+    submission
   );
 }