Merge branch 'alpha' into refactoring_4

Author: Wandalen

module/move/assistant/.key/readme.md

@@ -0,0 +1,20 @@
+# Keys
+
+This document provides a concise example of an environment configuration script, used to set up environment variables for a project. These variables configure application behavior without altering the code.
+
+## Example of `.key/-env.sh`
+
+```bash
+# OpenAI API key.
+OPENAI_API_KEY=sk-proj-ABCDEFG
+```
+
+## How to Use in Shell
+
+To apply these variables to your current shell session, use:
+
+```bash
+. ./key/-env.sh
+```
+
+This command sources the script, making the variables available in your current session. Ensure `-env.sh` is in the `key` directory relative to your current location.

module/move/assistant/Cargo.toml

@@ -15,6 +15,7 @@ Assist AI in writing code.
 """
 categories = [ "algorithms", "development-tools" ]
 keywords = [ "fundamental", "general-purpose" ]
+default-run = "main"
 
 [lints]
 workspace = true
@@ -32,6 +33,14 @@ enabled = [
   "reflect_tools/enabled",
 ]
 
+[[bin]]
+name = "main"
+path = "src/bin/main.rs"
+
+[[bin]]
+name = "list_resources"
+path = "src/bin/list_resources.rs"
+
 [dependencies]
 # xxx : qqq : optimze features
 mod_interface = { workspace = true, features = [ "full" ] }
@@ -41,6 +50,12 @@ reflect_tools = { workspace = true, features = [ "full" ] }
 openai-api-rs = { version = "=5.0.11" }
 tokio = { version = "1", features = ["full"] }
 dotenv = "0.15"
+clap = { version = "4.5.20", features = ["derive"] }
+pth = "0.21.0"
+serde = { version = "1.0.213", features = ["derive"] }
+serde_with = "3.11.0"
+error_tools = "0.17.0"
+derive_tools = { version = "0.32.0", features = ["full"] }
 
 [dev-dependencies]
 test_tools = { workspace = true }

module/move/assistant/design/commands.md

@@ -0,0 +1,73 @@
+# Commands
+
+## Legend
+
+- `<...>` - argument.
+- `<..?>` - optional argument.
+- `<...=...>` - argument with default value.
+- `(...)+` - one or more times.
+
+## OpenAI
+
+### Files
+
+```shell
+assistant openai files upload <path> <purpose>
+assistant openai files list
+assistant openai files retrieve <id>
+assistant openai files delete <id>
+assistant openai files retrieve-content <id>
+```
+
+### Assistants
+
+```shell
+assistant openai assistants create <model> <name?> <description?> <instructions?>
+assistant openai assistants list
+assistant openai assistants retrieve <id>
+assistant openai assistants modify <id> <model?> <name?> <description?> <instructions?>
+assistant openai assistants delete <id>
+```
+
+### Threads
+
+```shell
+assistant openai threads create
+assistant openai threads retrieve <id>
+assistant openai threads delete <id>
+```
+
+### Messages
+
+```shell
+assistant openai messages create <thread_id> <role> <content>
+assistant openai messages list <thread_id>
+assistant openai messages retrieve <thread_id> <message_id>
+assistant openai messages modify <thread_id> <message_id>
+assistant openai messages delete <thread_id> <message_id>
+```
+
+### Chat
+
+```shell
+assistant openai chat create-completion (<role> <message>)+
+```
+
+### Runs
+
+```shell
+assistant openai runs create <thread_id> <assistant_id>
+assistant openai runs create-with-thread <assistant_id> <user_message>
+assistant openai runs list <thread_id>
+assistant openai runs retrieve <thread_id> <run_id>
+assistant openai runs cancel <thread_id> <run_id>
+```
+
+## Anthropic
+
+### Messages
+
+```shell
+assistant anthropic messages create (<role> <message>)+
+```
+

module/move/assistant/design/entities.mmd

@@ -0,0 +1,78 @@
+---
+title: OpenAI API
+---
+erDiagram
+    File {
+        string id PK
+        string object
+        integer bytes
+        integer created_at
+        string file_name
+        string purpose
+    }
+
+    Assistant {
+        string id PK
+        string object
+        string model
+        integer created_at
+        string name
+        string description
+        string instructions
+        tool[] tools
+        metadata metadata
+        headers headers
+    }
+
+    Thread {
+        string id PK
+        string object
+        integer created_at
+        object tool_resources
+        metadata metadata
+    }
+
+    Message {
+        string id PK
+        string object
+        integer created_at
+        string thread_id FK
+        string status
+        object incomplete_details
+        integer completed_at
+        integer incomplete_at
+        string role
+        array content
+        string assistant_id FK
+        string run_id FK
+        array attachments
+        metadata metadata
+    }
+
+    Run {
+        string id PK
+        string object
+        integer created_at
+        string thread_id FK
+        string assistant_id FK
+        string status
+        object required_action
+        object last_error
+        integer expires_at
+        integer started_at
+        integer cancelled_at
+        integer failed_at
+        integer completed_at
+        object incomplete_details
+        string model
+        string instructions
+        tool[] tools
+        metadata metadata
+        headers headers
+    }
+    
+    Assistant |o--o{ Run : ""
+
+    Thread ||--o{ Message : ""
+    Thread ||--o{ Run: ""
+

module/move/assistant/design/entities.png

@@ -0,0 +1,32 @@
+# Scenarios
+
+## OpenAI
+
+### Assistants
+
+#### Make new assistant
+
+```shell
+assistant openai assistants create gpt-4o-mini CoolBot 'CoolBot is a helpful assistant.' 'You are a helpful assistant.'
+```
+
+This command will return assistant ID.
+
+#### Chat with the assistant
+
+To chat with OpenAI assistant, one should do this:
+
+1. Create a thread. Thread is like a chat.
+2. Write a message in thread (e.g. a question).
+3. Run the assistant in the thread.
+
+```shell
+assistant openai threads create
+```
+
+This command will return the new thread ID (referred as `thread_id`). To call an assistant, you need to know its ID.
+
+```shell
+assistant openai messages create <thread_id> user '2 + 2 = ?'
+assistant openai runs create <thread_id> <assistant_id>
+```

module/move/assistant/design/scenarios.md

@@ -0,0 +1,13 @@
+//!
+//! CLI actions of the tool.
+//!
+
+mod private {}
+
+crate::mod_interface!
+{
+  layer openai;
+  layer openai_assistants_list;
+  layer openai_files_list;
+  layer openai_runs_list;
+}

module/move/assistant/src/actions.rs

@@ -0,0 +1,44 @@
+//!
+//! OpenAI API actions.
+//!
+//! This module also contains the definition of OpenAI Error.
+//!
+
+mod private 
+{
+
+  use error_tools::typed::Error;
+  use derive_tools::{ AsRefStr };
+
+  use crate::*;
+  use ser::DisplayFromStr;
+
+  /// Collective enum for errors in OpenAI actions.
+  #[ ser::serde_as ]
+  #[ derive( Debug, Error, AsRefStr, ser::Serialize ) ]
+  #[ serde( tag = "type", content = "data" ) ]
+  pub enum Error
+  {
+    /// API error from the underlying implementation crate.
+    #[ error( "OpenAI API returned error:\n{0}" ) ]
+    ApiError
+    (
+      #[ from ] 
+      #[ serde_as( as = "DisplayFromStr" ) ] 
+      openai_api_rs::v1::error::APIError 
+    )
+  }
+
+  /// Shorthand for `Result` in OpenAI actions.
+  pub type Result< T > = core::result::Result< T, Error >;
+
+}
+
+crate::mod_interface!
+{
+  own use
+  {
+    Error,
+    Result
+  };
+}

module/move/assistant/src/actions/openai.rs

@@ -0,0 +1,68 @@
+//!
+//! List assistants in OpenAI API (action part).
+//!
+
+mod private
+{
+
+  use std::fmt;
+
+  use format_tools::
+  {
+    AsTable,
+    TableFormatter,
+    output_format,
+  };
+
+  use crate::*;
+  use client::Client;
+  use debug::AssistantObjectWrap;
+  use actions::openai::Result;
+
+  /// Report for `openai assistants list`.
+  #[ derive( Debug ) ]
+  pub struct ListReport
+  {
+    /// Show records as separate tables.
+    pub show_records_as_tables : bool,
+
+    /// OpenAI assistants.
+    pub assistants: Vec< AssistantObjectWrap >
+  }
+
+  impl fmt::Display for ListReport
+  {
+    fn fmt
+    ( 
+      &self, 
+      f : &mut fmt::Formatter< '_ >
+    ) -> fmt::Result
+    {
+      if self.show_records_as_tables
+      {
+        writeln!(f, "{}", AsTable::new( &self.assistants ).table_to_string_with_format( &output_format::Records::default() ) )
+      }
+      else
+      {
+        writeln!(f, "{}", AsTable::new( &self.assistants ).table_to_string_with_format( &output_format::Table::default() ) )
+      }
+    }
+  }
+
+  /// List OpenAI assistants action.
+  pub async fn action
+  (
+    client : &Client,
+    show_records_as_tables : bool,
+  ) -> Result < ListReport >
+  {
+    let response = client.list_assistant( None, None, None, None ).await?;
+    let assistants = response.data.into_iter().map( AssistantObjectWrap ).collect();
+    Ok( ListReport { show_records_as_tables, assistants } )
+  }
+}
+
+crate::mod_interface!
+{
+  own use action;
+}