arize-phoenix 10.0.4__py3-none-any.whl → 12.28.1__py3-none-any.whl

phoenix/db/README.md

@@ -64,11 +64,11 @@ erDiagram
         int id PK
         string name
         string cron_expression
-        json rule
+        jsonb rule
     }
 
     Project ||--o{ Trace : has
-    Project ||--o| ProjectTraceRetentionPolicy : has
+    Project ||--o{ ProjectSession : has
     Project ||--o{ ProjectAnnotationConfig : has
     Project {
         int id PK
@@ -82,6 +82,7 @@ erDiagram
     }
 
     ProjectSession ||--o{ Trace : has
+    ProjectSession ||--o{ ProjectSessionAnnotation : has
     ProjectSession {
         int id PK
         string session_id
@@ -115,8 +116,8 @@ erDiagram
         string span_kind
         datetime start_time
         datetime end_time
-        json attributes
-        json events
+        jsonb attributes
+        jsonb events
         string status_code
         string status_message
         int cumulative_error_count
@@ -132,9 +133,9 @@ erDiagram
         int document_position
         string name
         string label
-        float score
+        double score
         string explanation
-        json metadata
+        jsonb metadata
         string annotator_kind
         datetime created_at
         datetime updated_at
@@ -148,9 +149,9 @@ erDiagram
         int span_rowid FK
         string name
         string label
-        float score
+        double score
         string explanation
-        json metadata
+        jsonb metadata
         string annotator_kind
         datetime created_at
         datetime updated_at
@@ -164,9 +165,9 @@ erDiagram
         int trace_rowid FK
         string name
         string label
-        float score
+        double score
         string explanation
-        json metadata
+        jsonb metadata
         string annotator_kind
         datetime created_at
         datetime updated_at
@@ -177,25 +178,33 @@ erDiagram
 
     Dataset ||--o{ DatasetVersion : has
     Dataset ||--o{ DatasetExample : contains
+    Dataset ||--o{ Experiment : used_in
+    Dataset ||--o{ DatasetsDatasetLabel : has
+    Dataset ||--o{ ExperimentTag : tagged_with
     Dataset {
         int id PK
         string name
         string description
-        json metadata
+        jsonb metadata
         datetime created_at
         datetime updated_at
+        bigint user_id FK
     }
 
     DatasetVersion ||--o{ DatasetExampleRevision : has
+    DatasetVersion ||--o{ Experiment : used_in
     DatasetVersion {
         int id PK
         int dataset_id FK
         string description
-        json metadata
+        jsonb metadata
         datetime created_at
+        bigint user_id FK
     }
 
     DatasetExample ||--o{ DatasetExampleRevision : has
+    DatasetExample ||--o{ DatasetSplitsDatasetExample : belongs_to
+    DatasetExample ||--o{ ExperimentsDatasetExample : linked_in
     DatasetExample {
         int id PK
         int dataset_id FK
@@ -203,18 +212,22 @@ erDiagram
         datetime created_at
     }
 
+    DatasetExampleRevision ||--o{ ExperimentsDatasetExample : revision_used
     DatasetExampleRevision {
         int id PK
         int dataset_example_id FK
         int dataset_version_id FK
-        json input
-        json output
-        json metadata
+        jsonb input
+        jsonb output
+        jsonb metadata
         string revision_kind
         datetime created_at
     }
 
     Experiment ||--o{ ExperimentRun : has
+    Experiment ||--o{ ExperimentTag : has
+    Experiment ||--o{ ExperimentsDatasetExample : includes
+    Experiment ||--o{ ExperimentsDatasetSplit : uses
     Experiment {
         int id PK
         int dataset_id FK
@@ -222,20 +235,22 @@ erDiagram
         string name
         string description
         int repetitions
-        json metadata
+        jsonb metadata
         string project_name
         datetime created_at
         datetime updated_at
+        int user_id FK
     }
 
     ExperimentRun ||--o{ ExperimentRunAnnotation : has
+    DatasetExample ||--o{ ExperimentRun : used_in
     ExperimentRun {
         int id PK
         int experiment_id FK
         int dataset_example_id FK
         int repetition_number
         string trace_id
-        json output
+        jsonb output
         datetime start_time
         datetime end_time
         int prompt_token_count
@@ -249,15 +264,84 @@ erDiagram
         string name
         string annotator_kind
         string label
-        float score
+        double score
         string explanation
         string trace_id
         string error
-        json metadata
+        jsonb metadata
         datetime start_time
         datetime end_time
     }
 
+    DatasetSplit ||--o{ DatasetSplitsDatasetExample : contains
+    DatasetSplit ||--o{ ExperimentsDatasetSplit : used_in
+    DatasetSplit {
+        bigint id PK
+        string name
+        string description
+        string color
+        jsonb metadata
+        datetime created_at
+        datetime updated_at
+        bigint user_id FK
+    }
+
+    DatasetSplitsDatasetExample {
+        bigint dataset_split_id FK
+        bigint dataset_example_id FK
+    }
+
+    DatasetLabel ||--o{ DatasetsDatasetLabel : applies_to
+    DatasetLabel {
+        bigint id PK
+        string name
+        string description
+        string color
+        bigint user_id FK
+    }
+
+    DatasetsDatasetLabel {
+        int id PK
+        int dataset_id FK
+        int dataset_label_id FK
+    }
+
+    ExperimentTag {
+        bigint id PK
+        bigint experiment_id FK
+        bigint dataset_id FK
+        string name
+        string description
+        bigint user_id FK
+    }
+
+    ExperimentsDatasetExample {
+        bigint experiment_id FK
+        bigint dataset_example_id FK
+        bigint dataset_example_revision_id FK
+    }
+
+    ExperimentsDatasetSplit {
+        bigint experiment_id FK
+        bigint dataset_split_id FK
+    }
+
+    ProjectSessionAnnotation {
+        bigint id PK
+        bigint project_session_id FK
+        string name
+        string label
+        double score
+        string explanation
+        jsonb metadata
+        string annotator_kind
+        bigint user_id FK
+        string identifier
+        string source
+        datetime created_at
+        datetime updated_at
+    }
+
     User ||--o{ ApiKey : has
     User ||--o{ AccessToken : has
     User ||--o{ RefreshToken : has
@@ -267,6 +351,13 @@ erDiagram
     User ||--o{ SpanAnnotation : has
     User ||--o{ DocumentAnnotation : has
     User ||--o{ TraceAnnotation : has
+    User ||--o{ ProjectSessionAnnotation : has
+    User ||--o{ Experiment : creates
+    User ||--o{ ExperimentTag : creates
+    User ||--o{ DatasetLabel : creates
+    User ||--o{ Dataset : creates
+    User ||--o{ DatasetVersion : creates
+    User ||--o{ DatasetSplit : creates
     User {
         int id PK
         int user_role_id FK
@@ -298,6 +389,7 @@ erDiagram
         datetime expires_at
     }
 
+    RefreshToken ||--o| AccessToken : creates
     AccessToken {
         int id PK
         int user_id FK
@@ -323,13 +415,13 @@ erDiagram
     Prompt ||--o{ PromptVersion : has
     Prompt ||--o{ PromptPromptLabel : has
     Prompt ||--o{ PromptVersionTag : has
-    Prompt ||--o{ Prompt : has
+    Prompt ||--o{ Prompt : derived_from
     Prompt {
         int id PK
         int source_prompt_id FK
         string name
         string description
-        json metadata
+        jsonb metadata
         datetime created_at
         datetime updated_at
     }
@@ -342,13 +434,13 @@ erDiagram
         int user_id FK
         string template_type
         string template_format
-        json template
-        json invocation_parameters
+        jsonb template
+        jsonb invocation_parameters
         json tools
         json response_format
         string model_provider
         string model_name
-        json metadata
+        jsonb metadata
         datetime created_at
     }
 
@@ -379,7 +471,7 @@ erDiagram
     AnnotationConfig {
         int id PK
         string name
-        json config
+        jsonb config
     }
 
     ProjectAnnotationConfig {
@@ -387,4 +479,482 @@ erDiagram
         int project_id FK
         int annotation_config_id FK
     }
+
+    GenerativeModel ||--o{ TokenPrice : has
+    GenerativeModel ||--o{ SpanCost : used_in
+    GenerativeModel {
+        bigint id PK
+        string name
+        string provider
+        string name_pattern
+        boolean is_built_in
+        datetime start_time
+        datetime created_at
+        datetime updated_at
+        datetime deleted_at
+    }
+
+    TokenPrice {
+        bigint id PK
+        bigint model_id FK
+        string token_type
+        boolean is_prompt
+        double base_rate
+        json customization
+    }
+
+    SpanCost ||--o{ SpanCostDetail : has
+    SpanCost {
+        bigint id PK
+        bigint span_rowid FK
+        bigint trace_rowid FK
+        bigint model_id FK
+        datetime span_start_time
+        double total_cost
+        double total_tokens
+        double prompt_cost
+        double prompt_tokens
+        double completion_cost
+        double completion_tokens
+    }
+
+    SpanCostDetail {
+        bigint id PK
+        bigint span_cost_id FK
+        string token_type
+        boolean is_prompt
+        double cost
+        double tokens
+        double cost_per_token
+    }
+```
+
+---
+
+## Focused Relationship Views
+
+> **Note**: The following subsection diagrams show simplified table structures focusing only on foreign keys to highlight relationships. These tables contain additional columns (including primary keys and other fields) not shown here - refer to the comprehensive ERD above for complete table definitions.
+
+### Core Tracing & Projects
+
+This subgroup represents the core functionality of Phoenix - projects organize traces into sessions, traces contain spans, and retention policies manage data lifecycle:
+
+```mermaid
+erDiagram
+    ProjectTraceRetentionPolicy ||--o{ Project : applied_to
+    ProjectTraceRetentionPolicy {
+    }
+
+    Project ||--o{ ProjectSession : has
+    Project ||--o{ Trace : has
+    Project {
+        int trace_retention_policy_id FK
+    }
+
+    ProjectSession ||--o{ Trace : has
+    ProjectSession {
+        int project_id FK
+    }
+
+    Trace ||--o{ Span : contains
+    Trace {
+        int project_rowid FK
+        int project_session_rowid FK
+    }
+
+    Span {
+        int trace_rowid FK
+        string parent_id
+    }
+```
+
+### Datasets & Data Management
+
+This subgroup shows how datasets are created from spans, organized with versions and splits, and labeled for better organization:
+
+```mermaid
+erDiagram
+    User ||--o{ DatasetLabel : creates
+    User ||--o{ Dataset : creates
+    User ||--o{ DatasetSplit : creates
+    User ||--o{ DatasetVersion : creates
+    User {
+    }
+
+    Trace ||--o{ Span : contains
+    Trace {
+    }
+
+    Span ||--o{ DatasetExample : becomes
+    Span {
+        int trace_rowid FK
+    }
+
+    Dataset ||--o{ DatasetVersion : has
+    Dataset ||--o{ DatasetExample : contains
+    Dataset ||--o{ DatasetsDatasetLabel : has
+    Dataset {
+        bigint user_id FK
+    }
+
+    DatasetVersion ||--o{ DatasetExampleRevision : has
+    DatasetVersion {
+        int dataset_id FK
+        bigint user_id FK
+    }
+
+    DatasetExample ||--o{ DatasetExampleRevision : has
+    DatasetExample ||--o{ DatasetSplitsDatasetExample : belongs_to
+    DatasetExample {
+        int dataset_id FK
+        int span_rowid FK
+    }
+
+    DatasetExampleRevision {
+        int dataset_example_id FK
+        int dataset_version_id FK
+    }
+
+    DatasetSplit ||--o{ DatasetSplitsDatasetExample : contains
+    DatasetSplit {
+        bigint user_id FK
+    }
+
+    DatasetSplitsDatasetExample {
+        bigint dataset_split_id FK
+        bigint dataset_example_id FK
+    }
+
+    DatasetLabel ||--o{ DatasetsDatasetLabel : applies_to
+    DatasetLabel {
+        bigint user_id FK
+    }
+
+    DatasetsDatasetLabel {
+        int dataset_id FK
+        int dataset_label_id FK
+    }
+```
+
+### Experiments & Evaluation
+
+This subgroup shows how experiments use datasets to run evaluations, track results, and organize findings with tags and annotations:
+
+```mermaid
+erDiagram
+    User ||--o{ Experiment : creates
+    User ||--o{ ExperimentTag : creates
+    User {
+    }
+
+    Dataset ||--o{ Experiment : used_in
+    Dataset {
+    }
+
+    DatasetVersion ||--o{ Experiment : used_in
+    DatasetVersion {
+    }
+
+    DatasetExample ||--o{ ExperimentRun : used_in
+    DatasetExample ||--o{ ExperimentsDatasetExample : linked_in
+    DatasetExample {
+    }
+
+    DatasetExampleRevision ||--o{ ExperimentsDatasetExample : revision_used
+    DatasetExampleRevision {
+    }
+
+    DatasetSplit ||--o{ ExperimentsDatasetSplit : used_in
+    DatasetSplit {
+    }
+
+    Experiment ||--o{ ExperimentRun : has
+    Experiment ||--o{ ExperimentTag : has
+    Experiment ||--o{ ExperimentsDatasetExample : includes
+    Experiment ||--o{ ExperimentsDatasetSplit : uses
+    Experiment {
+        int dataset_id FK
+        int dataset_version_id FK
+        bigint user_id FK
+    }
+
+    ExperimentRun ||--o{ ExperimentRunAnnotation : has
+    ExperimentRun {
+        int experiment_id FK
+        int dataset_example_id FK
+        string trace_id
+    }
+
+    ExperimentRunAnnotation {
+        int experiment_run_id FK
+    }
+
+    ExperimentTag {
+        bigint experiment_id FK
+        bigint dataset_id FK
+        bigint user_id FK
+    }
+
+    ExperimentsDatasetExample {
+        bigint experiment_id FK
+        bigint dataset_example_id FK
+        bigint dataset_example_revision_id FK
+    }
+
+    ExperimentsDatasetSplit {
+        bigint experiment_id FK
+        bigint dataset_split_id FK
+    }
+```
+
+### User Management & Authentication
+
+This subgroup shows how users are managed with roles and different authentication methods:
+
+```mermaid
+erDiagram
+    UserRole ||--o{ User : has
+    UserRole {
+    }
+
+    User ||--o{ ApiKey : has
+    User ||--o{ AccessToken : has
+    User ||--o{ RefreshToken : has
+    User ||--o{ PasswordResetToken : has
+    User {
+        int user_role_id FK
+    }
+
+    ApiKey {
+        int user_id FK
+    }
+
+    RefreshToken ||--o| AccessToken : creates
+    RefreshToken {
+        int user_id FK
+    }
+
+    AccessToken {
+        int user_id FK
+        int refresh_token_id FK
+    }
+
+    PasswordResetToken {
+        int user_id FK
+    }
+```
+
+### Annotations
+
+This subgroup shows how annotations are attached to spans, documents, traces, and project sessions, including their configuration:
+
+```mermaid
+erDiagram
+    Project ||--o{ ProjectAnnotationConfig : has
+    Project ||--o{ ProjectSession : has
+    Project ||--o{ Trace : has
+    Project {
+    }
+
+    ProjectSession ||--o{ ProjectSessionAnnotation : has
+    ProjectSession {
+        int project_id FK
+    }
+
+    Trace ||--o{ Span : contains
+    Trace ||--o{ TraceAnnotation : has
+    Trace {
+        int project_rowid FK
+    }
+
+    Span ||--o{ SpanAnnotation : has
+    Span ||--o{ DocumentAnnotation : has
+    Span {
+        int trace_rowid FK
+    }
+
+    User ||--o{ SpanAnnotation : creates
+    User ||--o{ DocumentAnnotation : creates
+    User ||--o{ TraceAnnotation : creates
+    User ||--o{ ProjectSessionAnnotation : creates
+    User {
+    }
+
+    AnnotationConfig ||--o{ ProjectAnnotationConfig : configures
+    AnnotationConfig {
+    }
+
+    ProjectAnnotationConfig {
+        int project_id FK
+        int annotation_config_id FK
+    }
+
+    SpanAnnotation {
+        int span_rowid FK
+        int user_id FK
+    }
+
+    DocumentAnnotation {
+        int span_rowid FK
+        int user_id FK
+    }
+
+    TraceAnnotation {
+        int trace_rowid FK
+        int user_id FK
+    }
+
+    ProjectSessionAnnotation {
+        bigint project_session_id FK
+        bigint user_id FK
+    }
+```
+
+### Prompts
+
+This subgroup shows how users create and manage prompt templates, versions, labels, and tags:
+
+```mermaid
+erDiagram
+    User ||--o{ PromptVersion : creates
+    User ||--o{ PromptVersionTag : creates
+    User {
+    }
+
+    Prompt ||--o{ PromptVersion : has
+    Prompt ||--o{ PromptPromptLabel : has
+    Prompt ||--o{ PromptVersionTag : has
+    Prompt ||--o{ Prompt : derived_from
+    Prompt {
+        int source_prompt_id FK
+    }
+
+    PromptVersion ||--o{ PromptVersionTag : has
+    PromptVersion {
+        int prompt_id FK
+        int user_id FK
+    }
+
+    PromptLabel ||--o{ PromptPromptLabel : has
+    PromptLabel {
+    }
+
+    PromptPromptLabel {
+        int prompt_label_id FK
+        int prompt_id FK
+    }
+
+    PromptVersionTag {
+        int prompt_id FK
+        int prompt_version_id FK
+        int user_id FK
+    }
 ```
+
+### Cost & Pricing
+
+This subgroup shows how LLM costs are calculated and tracked for spans and traces:
+
+```mermaid
+erDiagram
+    Trace ||--o{ Span : contains
+    Trace ||--o{ SpanCost : tracks
+    Trace {
+    }
+
+    Span ||--o{ SpanCost : generates
+    Span {
+        int trace_rowid FK
+    }
+
+    GenerativeModel ||--o{ TokenPrice : defines
+    GenerativeModel ||--o{ SpanCost : calculates
+    GenerativeModel {
+    }
+
+    TokenPrice {
+        bigint model_id FK
+    }
+
+    SpanCost ||--o{ SpanCostDetail : has
+    SpanCost {
+        bigint span_rowid FK
+        bigint trace_rowid FK
+        bigint model_id FK
+    }
+
+    SpanCostDetail {
+        bigint span_cost_id FK
+    }
+```
+
+### User-Created Content
+
+This subgroup shows all entities that track user ownership through user_id foreign keys, representing content created or managed by users across datasets, experiments, prompts, and annotations:
+
+```mermaid
+erDiagram
+    User ||--o{ Dataset : creates
+    User ||--o{ DatasetVersion : creates
+    User ||--o{ DatasetSplit : creates
+    User ||--o{ DatasetLabel : creates
+    User ||--o{ Experiment : creates
+    User ||--o{ ExperimentTag : creates
+    User ||--o{ PromptVersion : creates
+    User ||--o{ PromptVersionTag : creates
+    User ||--o{ SpanAnnotation : creates
+    User ||--o{ DocumentAnnotation : creates
+    User ||--o{ TraceAnnotation : creates
+    User ||--o{ ProjectSessionAnnotation : creates
+    User {
+    }
+
+    Dataset {
+        bigint user_id FK
+    }
+
+    DatasetVersion {
+        bigint user_id FK
+    }
+
+    DatasetSplit {
+        bigint user_id FK
+    }
+
+    DatasetLabel {
+        bigint user_id FK
+    }
+
+    Experiment {
+        bigint user_id FK
+    }
+
+    ExperimentTag {
+        bigint user_id FK
+    }
+
+    PromptVersion {
+        int user_id FK
+    }
+
+    PromptVersionTag {
+        int user_id FK
+    }
+
+    SpanAnnotation {
+        int user_id FK
+    }
+
+    DocumentAnnotation {
+        int user_id FK
+    }
+
+    TraceAnnotation {
+        int user_id FK
+    }
+
+    ProjectSessionAnnotation {
+        bigint user_id FK
+    }
+```
+