@dataclouder/ngx-agent-cards 0.0.75

package/README.md

@@ -0,0 +1,314 @@
+# Description
+
+This is an experimental and unstable Angular library for chatting with AI assistants.
+
+Uses the concept of character Specifications but improves with this new concept called ConversationAI.
+
+## Settings
+
+The library depends on your own connections with LLMs, so you need to provide a service that implements the specifications.
+
+Any model works well.
+
+Provide this service in your `main.ts` using the function `provideChatAIService`:
+
+```typescript
+import { provideChatAIService } from '@dataclouder/ngx-agent-cards';
+
+provideChatAIService(AgentCardsService);
+```
+
+Create your own service implementing the interface:
+
+```typescript
+import { AgentCardsAbstractService } from '@dataclouder/ngx-agent-cards';
+
+export class AgentCardsService implements AgentCardsAbstractService {
+  constructor(private httpService: HttpService, private userService: UserService) {}
+
+  public async callChatCompletion(conversation: ConversationPromptSettings): Promise<any> {
+    // Implementation here
+  }
+}
+```
+
+### Dependencies
+
+1. Angular Core
+
+2. Angular cdk only for internal dialog, dont forget to include css
+   @import '@angular/cdk/overlay-prebuilt.css';
+
+3. @dataclouder/storage-uploader to upload to GCP
+
+```
+    "@angular/common": ">=18.0.0",
+    "@angular/core": ">=18.0.0",
+    "@angular/cdk": ">=18.0.0",
+    "@dataclouder/storage-uploader": ">=0.0.4"
+```
+
+### Implementing Abstract Service
+
+in order to make this library compatible with your own logic you have provide a service implemeting AgentCardsAbstractService.
+
+```
+
+export abstract class AgentCardsAbstractService {
+  // call the llm to implement the completion
+  abstract callChatCompletion(conversation: ConversationDTO): Promise<any>;
+  // get the id of your card
+  abstract findConversationCard(id: string): Promise<IAgentCard>;
+  // get all conversation cards
+  abstract getAllConversationCards(): Promise<IAgentCard[]>;
+
+  abstract saveConversationCard(conversation: IAgentCard): Promise<IAgentCard>;
+
+  abstract deleteConversationCard(id: string): Promise<IAgentCard>;
+
+  abstract getTextAudioFile(tts: any): Promise<any>;
+
+  abstract getConversationUserSettings(): Promise<ChatUserSettings>;
+
+  abstract getConversationChatSettings(): Promise<ConversationPromptSettings>;
+
+  // strategy to save converstionUserSettings.
+  abstract saveConversationUserChatSettings(conversation: ChatUserSettings): Promise<ChatUserSettings>;
+}
+```
+
+### Components
+
+![Component Diagram](./docs/componentes_diagram.jpg)
+
+- **ConversationCardListsComponent**: Connects with backends shows availible conversations.
+
+- **DcAgentCardDetailsComponent**: Visualize Conversation Card details and start a conversation.
+
+- **DCChatComponent**: Start a conversation:
+
+<div style="display: flex; align-items: flex-start; gap: 20px;">
+  <div style="flex: 1">
+    <strong> *DCAgentCardFormComponent</strong>: This component is used to manage the conversation card data.
+  </div>
+  <div style="flex: 1">
+    <img src="./docs/conversation-form.png" alt="Component Diagram">
+  </div>
+</div>
+
+<div style="display: flex; align-items: flex-start; gap: 20px;">
+  <div style="flex: 1">
+    <strong> *DCChatSettingsComponent</strong>: this is use to change chat settings
+  </div>
+  <div style="flex: 1">
+    <img src="./docs/chat-settings.png" alt="Component Diagram">
+  </div>
+</div>
+- **ChatMessageComponent**
+
+## Changing CSS components.
+
+There are 3 options, to custom a DC component.
+
+1. HARD: totaly custom: need to know the libraries, import the raw components and rewrite the logic, or copy same logic just change what you need.
+2. Pass the component you want to substitude. WIP
+
+3. EASY: Pass the CSS.
+
+## About conversations tecnical explanation
+
+Character AI is evolving quickly, but there is no clear path on who is leading or proposing new standards.
+
+For now, all implementations contain V2 of character AI.
+
+This project contains better explanations about a Char.
+
+https://github.com/Bronya-Rand/Prom-Spec-V3
+
+This project goes beyond that, providing a new abstraction that can contain one or multiple characters and more conditions for the characters' interactions.
+
+I call this:
+
+Conversation AI V1
+
+Here are the specs for V1:
+
+This first version can only have one character. I need to understand a little bit more to create conversations with multiple characters, which I'll include in the second version.
+
+```typescript
+export interface IAgentCard {
+  version: string;
+  id: string;
+  title: string;
+
+  characterCard: CharaCard;
+
+  textEngine: TextEngines;
+  conversationType: ScenarioType;
+  lang: string;
+
+  tts: {
+    voice: string;
+    secondaryVoice: string;
+    speed: string;
+    speedRate: number;
+  };
+
+  metaApp: {
+    isPublished: boolean;
+    isPublic: any;
+    authorId: string;
+    authorEmail: string;
+    createdAt: Date;
+    updatedAt: Date;
+    takenCount: number;
+  };
+}
+```
+
+`characterCard`: The card you want to use to talk.
+
+`textEngine`: In order to read text, there are multiple formats in markdown. Depending on your format, the engine needs to read and highlight in different ways. Also, the app itself can create its own engine to add more functionalities.
+
+`conversationType`: This can be general purpose just to tag it, or the app can modify the conversation depending on the type.
+
+`lang`: The main language where the app is intended to operate.
+
+`tts`: Extra functionalities to add TTS. I need to think more on this. In the future, voices will probably be free or downloadable. For now, it is only the ID of the voice. There are only two voices in the first approach.
+
+`metaApp`: Everything your app needs to work. Audit data, how many times your app has been used, if the conversation is a challenge type, you can count how many passed or failed, etc.
+
+### How works
+
+multiple systems need to use chats, and add functionalities for chatting.
+
+This functionality is usually the same.
+
+Conversation Types
+
+- General
+- Reflextion:
+- Role Play
+- Role Play With Narrador
+- Challenge
+
+### How User and Chat Settings works.
+
+This is one of the biggest problems, app need to handle this an provide a service that is able to retrive this settings.
+
+There are multiple ways to use the chat, and there are
+functionalities availible, Users can save this functions and thats why you need the object ChatUserSettings,
+Chat are settings that does not depend on the user but in the application.
+
+Check the object.
+
+#### ChatUserSettings
+
+Conversation Chat User Settings.
+This is an implementation app can handle, it can be locally settings by defult saving on browers or DB.
+basically user have the object ChatUserSettings
+
+```typescript
+export class ChatUserSettings {
+  realTime: boolean;
+  repeatRecording: boolean;
+  fixGrammar: boolean;
+  superHearing: boolean;
+  voice: string;
+  autoTranslate: boolean;
+  highlightWords: boolean;
+  synthVoice: boolean;
+  modelName: string;
+  provider: string;
+  speed: string;
+  speedRate: number; // temporal
+}
+```
+
+#### ConversationPromptSettings
+
+```typescript
+export class ConversationPromptSettings {
+  messages?: ChatMessage[];
+  last_prompt?: string;
+  conversationType?: ConversationType;
+  textEngine?: string;
+  voice?: string; // first voice
+  secondaryVoice?: string; // apply for narrator
+  overrideConversationSettings?: Partial<ChatUserSettings>;
+}
+```
+
+Those are object to need to think how to store, create and pass to the chat.
+
+### How to parse conversation instructions.
+
+In order to adapt the conversartion to the current user, Character Cards use some wild words that are parsed before conversation start, so LLM is aware of name age and other data to make a custum conversation.
+
+this Wilds are
+
+{{user}}:
+{{}}:
+
+Polilan add more wilds for the same porpuse that helps to add context.
+
+{{word}}: is the words the user is studing
+{{targe}}: is the language the user wants to learn
+{{base}}: is the user native language
+
+TODO: this same logic can apply for every diferent app, think on how to abstract and create standard for this.
+
+##### Build messages to start a conversation
+
+- conversation need attached all the data from the character card.
+- this is my format.
+
+![Component Diagram](./docs/parsing_conversation.png)
+
+### Componentes in details
+
+1. **DCDCAgentCardFormComponent**
+
+#### Inputs:
+
+**conversationCardId**: string; is the id for the conversation to modify will look up for this in api otherwise is empty card. if is not passed will look for the id in the URL.
+
+**storageSettings**: StorageSettings: you can override the default setting for cropping:
+{ cropImageSettings: { path: '', fileName: '', resizeToWidth: 450 }, ratioType: AspectType.Vertical_9_16, resolutions: [ResolutionType.MediumLarge], };
+
+#### Outputs
+
+onImageLoaded: when the image is loaded in the storage.
+
+onSave: when user click save
+
+2. **ChatComponent**
+
+### Inputs
+
+**chatUserSettings** : if you want to hardcode the settings, otherwise will use the provided AgentCardsAbstractService
+
+**conversationCardId**:
+
+### Outputs
+
+### How to add TTS.
+
+There are multiple services that impruve Speaking App Capabilities, i think in future backend will handle all of them and front will only send the settings.
+
+For now backend need to implement a service. tts.
+
+### How to build and publish new version of this library
+
+the component need the cropper as dependency, make sure you already installed or compile that library.
+inside the angular
+is required to build first the dependencies locally
+
+npm run build:storage-uploader
+npm run build:core-components
+npm run publish:conversations
+
+after that i recommend to remove /dist folder, why ? becouse project path is linked to dist folder first if exits, and the to the source code. so in order to code easier i recommend to remove the dist folder.
+
+- npm run build
+- npm run publish