Skip to content

GLOSSARY.md

Latest commit

 

History

History
579 lines (478 loc) · 24.6 KB

GLOSSARY.md

File metadata and controls

579 lines (478 loc) · 24.6 KB

Glossary

Table of Contents

Chain-of-Thought

Definition: A step-by-step reasoning process that breaks down a complex task into smaller, logical sub-questions or steps.
Project Context: Used to guide progressive reasoning (e.g., clarifying the problem, identifying sub-questions, synthesizing results) and to organize the execution flow within the pipeline.

Pipeline

Definition: A structured sequence of operations or processing steps that transforms and processes data sequentially (or in parallel) to yield a final result.
Project Context: Represented by the TPipeline collection, which holds instances of TPromiseParams corresponding to various asynchronous execution steps.

Scheduler

Definition: A component responsible for orchestrating the execution of asynchronous tasks. It manages triggering, chaining of steps, and error handling.
Project Context: The TAsyncScheduler organizes the execution of the defined pipeline steps and ensures that each promise is processed in the expected order, relaying errors when necessary.

Promise / TPromise

Definition: An abstraction that represents an asynchronous operation that will eventually yield a result (either fulfilled or rejected).
Project Context: The generic class TPromise<T> implements this concept in Delphi, providing methods such as &Then and &Catch for chaining and handling callbacks.

TPromiseParams / TParameters

Definition: A class that stores and transmits parameters as key-value pairs.
Project Context: TPromiseParams inherits from TParameters and offers fluent-style setters (e.g., Input, Model, OutputType, etc.) to configure each step of the pipeline.

Prototype

Definition: In this project, Prototype refers to an initial, pre-configured instance of TPromiseParams that serves as a template for creating new instances.
Project Context: Cloning this prototype makes it easier to duplicate the base configuration for each asynchronous execution step, ensuring consistency in parameter transmission and simplifying the initialization of new promises.

TPromiseEvents

Definition: An abstract class that defines the key events of a promise, including methods to execute before (BeforeExec), after (AfterExec), and during (Execute) the processing of an asynchronous task.
Project Context: Derived classes such as TScheduleEvents or TScheduleParallelEvents implement these methods to define the specific behavior for each step.

ChainProcessor

Definition: A component that manages the chaining and aggregation of outputs (both textual and JSON) generated by different steps in the thought process.
Project Context: It updates the pipeline, aggregates results, and prepares data for subsequent steps.

TSampleChainExecutor

Definition: An example component that orchestrates the complete execution of an asynchronous processing chain.
Project Context: It defines and manages the order of steps (initialization, web search, synthesis, final writing) and coordinates interactions between the pipeline, scheduler, and file manager.

IoC Container

Definition: An Inversion of Control container that manages and resolves dependencies between components.
Project Context: Used to register and inject services (e.g., IGenAI, IDisplayer, ICancellation, etc.), thereby facilitating modularity and testability within the code.

Displayer

Definition: An interface or component responsible for presenting information to the user.
Project Context: Examples include TEdgeDisplayerVCL for display via an Edge browser and TMemoDisplayerVCL for display in a Memo component.

OpenAIPromise / TOpenAIPromise

Definition: An implementation of a promise for interacting with the OpenAI API via asynchronous requests.
Project Context: Used to send requests in streaming mode (via AsyncCreateStream) and to handle real-time API responses.

OpenAIParallelPromise / TOpenAIParallelPromise

Definition: A variant of the promise that enables parallel execution of requests to OpenAI, ideal for handling multiple simultaneous queries.
Project Context: Employed for parallel web searches, aggregating results from several sub-questions.

PromiseAIFileManager / TPromiseAIFileManager

Definition: A component responsible for generating a filename via OpenAI and saving data (both results and final text) to files.
Project Context: Facilitates the export of results by invoking OpenAI to create an appropriate filename and saving the content to the file system.

Cancellation

Definition: An interface or component that allows an ongoing asynchronous operation to be canceled.
Project Context: Enables interruption of streaming or stopping a request in the event of an error or upon user request.

Streaming

Definition: The process of receiving and displaying data progressively as it becomes available.
Project Context: Utilized during OpenAI requests (via AsyncCreateStream) to update the display in a fluid and responsive manner.

TPipeline

Definition: A collection of TPromiseParams instances representing each step of the asynchronous processing chain.
Project Context: It aggregates and manages all the steps to be executed within the processing pipeline.

TChainOfThoughts

Definition: A collection that groups instances of TChainOfThought, each containing detailed content for a particular step or piece of reasoning within the thought chain.
Project Context: Used to store and utilize the information generated during the breakdown and analysis of the initial question.

IPromisePlugin

Definition: A generic interface representing a plugin capable of executing a promise for a given type of parameters.
Project Context: Implemented by TOpenAIPromise and TOpenAIParallelPromise to encapsulate the asynchronous execution of OpenAI requests.

Diagrams

Overview (UI + Logic + Services) - With Parallel Web Search

Note

This diagram provides an overall view of the system by showing how the user interface (the form, EdgeBrowser, memos, buttons) integrates with the business logic and backend services.

UI (Form1): Displays the visual elements that trigger execution (buttons, streaming display via EdgeBrowser, memo panels).

  • IoC Container: Manages dependency injection for components such as the OpenAI client, display managers for streaming, and error handling.
  • Execution Logic: Highlights the roles of components like TScheduleEvents and TSampleChainExecutor, which handle both sequential and parallel asynchronous processing, culminating in saving the final results via TOpenAIFileManager.
  • Models Used: Indicates the various models (e.g., "gpt-4o-mini", "gpt-4o-mini-search-preview", "gpt-4o") that guide the response generation.

This diagram serves as a starting point to understand how the various components interact on a global scale.

Form1 (UI)
├── EdgeBrowser1 → TEdgeBrowser
├── Memo1, Memo2 → TMemo
├── Button1 / Button2 / Button3
├── IoC Container
│   ├── IGenAI → TGenAIFactory
│   ├── IDisplayer
│   │   ├── EdgeDisplayer → TEdgeDisplayerVCL
│   │   └── MemoDisplayer → TMemoDisplayerVCL
│   ├── ICancellation → TCancellationVCL
│   ├── IPromisePlugin<T> → TOpenAIPromise
│   ├── IPromisePlugin<T> → TOpenAIParallelPromise
│   ├── IAsyncScheduler → TAsyncScheduler
│   └── IPromiseFileManager → TPromiseAIFileManager
│
├── Button2Click
│   └── TScheduleEvents
│       └── TOpenAIPromise.Execute(TPromiseParams)
│
└── Button3Click
    └── TSampleChainExecutor
        ├── FPrompt, FClient, FPath, etc.
        ├── FChainProcessor
        │   ├── TPipeline (steps)
        │   ├── TChainOfThoughts
        │   └── TPromiseParams (prototype)
        ├── FScheduleEvents → TScheduleEvents
        ├── FScheduleParallelEvents → TScheduleEvents
        ├── FStepActions (TChainStepFunction[])
        ├── Execute()
        │   ├── RunFirstStep
        │   ├── RunNextStep (x3)
        │   │   └── Web Search Step (Using TOpenAIParallelPromise)
        │   └── RunLastStep
        └── FileManager.CreateFileNameAndSave()
            └── TOpenAIFileManager
                ├── BuildPrompt()
                ├── GetFileName()
                └── SaveToFile()

Models used
├── FDefaultModel → "gpt-4o-mini"
├── FSearchModel  → "gpt-4o-mini-search-preview"
└── FEditorModel  → "gpt-4o"

Units - Structure and Responsibilities

Note

This diagram details the functional breakdown of the project into modular units, each with a specific responsibility:

  • Async.Promise: The engine for promises that handles asynchronous execution, featuring states (Pending, Fulfilled, Rejected).
  • Async.Promise.Params: Manages configuration parameters with a fluent interface to set inputs, models, outputs, etc.
  • Async.Promise.Manager & Pipeline: Oversee the chain-of-thought, the processing pipeline, and result aggregation.
  • Specific Modules (OpenAI.Promise, OpenAI.FileManager, etc.): Handle interfacing with OpenAI for text generation and data storage.
  • Sample.SchedulerEvents and Sample.ChainExecutor: Demonstrate the orchestration of processing steps and a multi-step workflow.

This diagram helps clarify how the project is organized into modules, making maintenance and future expansion easier.

Units
├── Async.Promise
│   ├── TPromise<T> ← Core async logic
│   └── TPromiseState (Pending, Fulfilled, Rejected)
│
├── Async.Promise.Params
│   ├── TParameters → TPromiseParams
│   └── Fluent-style setters (Input, Model, OutputType, etc.)
│
├── Async.Promise.Manager
│   ├── TChainOfThought
│   ├── TPromiseEvents (abstract)
│   ├── TPipeline (List<TPromiseParams>)
│   └── TOutputTypeHelper
│
├── Async.Promise.Pipeline
│   ├── TChainProcessor
│   └── Handles pipeline steps, chain, and output aggregation
│
├── Sample.SchedulerEvents
│   └── TScheduleEvents (BeforeExec, AfterExec, Execute)
│
├── OpenAI.Promise
│   ├── TOpenAIPromise (IPromisePlugin<TPromiseParams>)
│   └── Uses Client.Chat.AsyncCreateStream
│
├── OpenAI.FileManager
│   ├── TOpenAIFileManager
│   ├── BuildPrompt()
│   ├── GetFileName()
│   └── SaveToFile()
│   └── Used via TPromiseAIFileManager
│
├── Sample.ChainExecutor
│   ├── TSampleChainExecutor
│   ├── AddStep()
│   ├── Execute()
│   └── Orchestrates multi-step async processing
│
├── OpenAI.ParallelPromise
│   ├── TOpenAIParallelPromise (IPromisePlugin<TPromiseParams>)
│   ├── Uses Client.Chat.CreateParallel()
│   └── Handles parallel web search execution (multi-query)
│
└── Async.Promise.ParallelManager
    ├── TParallelPromiseExecutor
    ├── Manages parallel promise chains
    └── Aggregates and synchronizes results from parallel tasks

Thought Chain Flow — Multi-step Reasoning + AI Prompting

Note

This diagram highlights the chain-of-thought process that structures the reasoning:

  • User Input: The user’s input forms the basis of the reasoning process.
  • Progressive Steps:
    • Clarification of the Question: Detects language and intent, formulates sub-questions, etc.
    • Web Search: Uses the generated sub-questions to perform parallel web searches and gather references.
    • Synthesis: Aggregates the data and formulates a structured JSON incorporating the thought process elements.
    • Final Writing: Generates a comprehensive text with a human, educational tone.
  • Output: Results are streamed to the EdgeBrowser display and saved as files.

This diagram helps understand the multi-step reasoning process and how each phase contributes to the final output.

User Input
└── Memo2.Text → Prompt

Step 1: Clarify the Question (CHAIN1)
└── TChainOfThought[]
    ├── Step 1: Detect Language & Intent
    ├── Step 2: Identify Dimensions
    ├── Step 3: Generate Sub-Questions
    ├── Step 4: Define Research Goals
    └── Step 5: Extract Relevant Sub-Questions (JSONL Output)
        ↓

Step 2: Web Search (CHAIN2 - dynamic)
└── Use sub-questions from JSONL (Step 5)
    ├── Query & Analyze via GPT Search Model
    ├── Aggregate Results (Text Format)
    └── Store into: `TextOutput`
        ↓

Step 3: Synthesis of Data (CHAIN3)
└── Use:
    ├── Main Prompt
    ├── TextOutput (from Web Search)
    ├── JSON Steps (from Step 1)
    └── Combine into:
        {
          "main_question": "...",
          "data_reference": "...",
          "json_steps": [...]
        }
    → Response as new TChainOfThoughts[]
        ↓

Step 4: Final Writing (CHAIN4)
└── Prompt: Full Synthesis + Philosophy
    ├── Human-style Writing
    ├── Bold, Pedagogical Tone
    ├── Referenced Examples with URLs
    └── Produces: Final Text (Markdown)
        ↓

Output
├── Display in EdgeDisplayer (Streaming)
├── Save as:
│   ├── "Results\*.md" (Final Text)
│   └── "Results\*.data" (JSON + Web Research)
└── Completion Message → ShowMessage("Process Completed.")

Component Diagram - Core Services & Chain Execution

Note

This diagram illustrates the component-oriented architecture linking the IoC Container with various services and modules:

  • IoC Container: Centralizes dependency injection for interfaces such as IGenAI, IDisplayer, ICancellation, etc.
  • Core Services: Details how promise modules (TOpenAIPromise, TOpenAIParallelPromise), the FileManager, and the Scheduler work together to orchestrate the complete workflow.
  • Execution Chain: Shows how TSampleChainExecutor coordinates the steps via TChainProcessor, passing through the pipeline and triggering asynchronous executions.
  • Component Interactions: Highlights the exchanges between the OpenAI client, display managers, and the saving mechanism.

This diagram offers a synthesized view of the interconnections among the different services, making it easier to grasp the overall project architecture.

IoC Container
├── IGenAI → TGenAIFactory
├── IDisplayer
│   ├── "browser" → TEdgeDisplayerVCL
│   └── "memo"    → TMemoDisplayerVCL
├── ICancellation → TCancellationVCL
├── IPromisePlugin<TPromiseParams> → TOpenAIPromise
├── IAsyncScheduler → TAsyncScheduler
├── IPromiseFileManager → TPromiseAIFileManager
└── IPromisePlugin<TPromiseParams> → TOpenAIParallelPromise

TSampleChainExecutor
├── Uses IGenAI
├── Uses IAsyncScheduler
├── Uses IPromiseFileManager
├── Uses TChainProcessor
│   ├── Holds TPipeline
│   ├── Holds TChainOfThoughts
│   └── Uses TPromiseParams (prototype)
│       └── Inherits from TParameters
├── Adds Step Functions (TChainStepFunction[])
└── Controls async execution flow
    ├── RunFirstStep()
    ├── RunNextStep() × N
    │   ├── Sequential Step
    │   └── Parallel Step (Web search)
    └── RunLastStep()

TPromise<T>
├── Core async engine
│   ├── State: Pending / Fulfilled / Rejected
│   ├── Chained: &Then / &Catch
│   └── Queue-safe via TThread.Queue()
└── Supports parallel execution through TPromise<T> and TOpenAIParallelPromise

TPromiseParams : TParameters
├── Fluent-style config
│   ├── Input / Output / Model / OutputType
│   ├── ChainSteps / Index / Client
│   └── SilentMode / Pipeline
└── Used across async calls and chains

TPromiseAIFileManager
├── Implements IPromiseFileManager
├── Uses TOpenAIFileManager internally
│   ├── BuildPrompt()
│   ├── GetFileName()
│   └── SaveToFile()
└── Used in final chain step for file export

TOpenAIPromise
├── Implements IPromisePlugin
├── Uses IGenAI.Chat.AsyncCreateStream
└── Calls & resolves Promises with streaming

TOpenAIParallelPromise
├── Implements IPromisePlugin
├── Uses IGenAI.Chat.CreateParallel
└── Handles parallel execution of web search steps

Sequence Diagram — Button3Click / TSampleChainExecutor Workflow

Note

This sequence diagram illustrates the complete execution flow triggered by the user's action (clicking Button3).

  • Initiation: The user’s action instantiates TSampleChainExecutor and begins the steps initialization (StepsInitialization).
  • Chained Execution: Different steps (RunFirstStep, RunNextStep, RunLastStep) are executed sequentially, with each step relying on the result of the previous one.
  • Asynchronous Processing: For each step, asynchronous events (handled via TScheduleEvents and either TOpenAIPromise or TOpenAIParallelPromise for web search) communicate with the OpenAI service, managing streaming and error handling.
  • Finalization: The final result is processed by the FileManager, which saves the outcomes as files.

This diagram allows to follow the asynchronous execution flow step-by-step and understand the logic behind the workflow.

User Action: Button3Click
└── TSampleChainExecutor.Create()
    ├── Params: Prompt, Models, Path, Client
    └── StepsInitialization()
        ├── Add Step 1: Analyze Question (CHAIN1)
        ├── Add Step 2: Web Search (dynamic)
        ├── Add Step 3: Synthesis (CHAIN3)
        └── Add Step 4: Write Final (CHAIN4)

    ↓

Execute()
└── RunFirstStep()
    └── StepAction[0] (CHAIN1: Analyze Question)
        └── ChainProcessor.Complete()
            └── Build TPromiseParams[] with ScheduleEvents
                └── Add to Pipeline
    └── AsyncScheduler.Execute(Pipeline)
        └── For each TPromiseParams:
            └── TScheduleEvents.Execute()
                └── TOpenAIPromise.Execute()
                    ├── Prepare prompt
                    └── Client.Chat.AsyncCreateStream()
                        ├── OnStart → Clear EdgeDisplayer
                        ├── OnProgress → Stream Display
                        ├── OnSuccess → Resolve()
                        └── OnError / OnCancellation → Reject()

    ↓

Then → RunNextStep()
└── StepAction[1] (Web Search - Dynamic)
    └── ChainProcessor.Complete()
    └── AsyncScheduler.Execute(Pipeline)
        └── For each TPromiseParams:
            └── TScheduleParallelEvents.Execute()
                └── TOpenAIParallelPromise.Execute()
                    ├── Prepare JSONL (Parallel Web Search)
                    └── Client.Chat.CreateParallel()
                        ├── OnStart → Show "Searching..."
                        ├── OnSuccess → Resolve JSONL Results
                        └── OnError / OnCancellation → Reject()

    ↓

Then → RunNextStep()
└── StepAction[2] (CHAIN3: Build JSON for Synthesis)
    └── ChainProcessor.Update()
    └── ChainProcessor.Complete()
    └── AsyncScheduler.Execute(Pipeline)
        └── For each TPromiseParams:
            └── TScheduleEvents.Execute()
                └── TOpenAIPromise.Execute()
                    ├── Prepare prompt
                    └── Client.Chat.AsyncCreateStream()
                        ├── OnStart → Clear EdgeDisplayer
                        ├── OnProgress → Stream Display
                        ├── OnSuccess → Resolve()
                        └── OnError / OnCancellation → Reject()

    ↓

Then → RunLastStep()
└── StepAction[3] (CHAIN4: Final Text)
    └── ChainProcessor.Update()
    └── ChainProcessor.Complete()
    └── AsyncScheduler.Execute(Pipeline)
        └── For each TPromiseParams:
            └── TScheduleEvents.Execute()
                └── TOpenAIPromise.Execute()
                    ├── Prepare Final Prompt
                    └── Client.Chat.AsyncCreateStream()
                        ├── OnStart → Clear EdgeDisplayer
                        ├── OnProgress → Stream Display
                        ├── OnSuccess → Resolve()
                        └── OnError / OnCancellation → Reject()
    └── Then → Set Final Text

    ↓

Then → FileManager.CreateFileNameAndSave()
└── TOpenAIFileManager.CreateFileNameAndSave()
    ├── BuildPrompt()
    ├── GetFileName()
    └── SaveToFile()

Async Task Flow — Promises, Streaming & Callbacks

Note

This diagram provides a detailed view of the internal workings of the promise system and asynchronous processing:

  • Initialization: Creation of TPromiseParams and the triggering of execution via TScheduleEvents.
  • Promise Lifecycle:
    • Pending: Callbacks are registered while the promise is waiting.
    • Resolution or Rejection: Successful or failed operations trigger callbacks via TThread.Queue to ensure UI thread safety.
  • Streaming: Real-time data streaming is managed through specific callbacks (OnStart, OnProgress, OnSuccess, OnError) that update the display live.
  • Error Handling: Errors and cancellations are properly relayed to halt the processing chain if necessary.

This diagram is key to understanding how asynchronous logic is implemented and how data streaming is managed within the system.

User Action (Button2Click / Button3Click)
└── Create TPromiseParams
    └── Set input, model, client, flags
    ↓

Call .Execute() on TScheduleEvents
└── Triggers OpenAIPromise.Execute(TPromiseParams)
    └── Returns: TPromise<string>
    ↓

TPromise<T> Engine
└── State: psPending
    └── Add .&Then() callbacks
    └── Add .&Catch() callbacks
    ↓

OpenAIPromise.Execute()
└── Prepare TChatParams
└── Call IGenAI.Chat.AsyncCreateStream()
    ↓

Asynchronous Stream Lifecycle
├── OnStart()
│   ├── Clear EdgeDisplayer (if not silent)
│   └── Init StreamBuffer
├── OnProgress()
│   ├── Append delta to StreamBuffer
│   └── Stream update to EdgeDisplayer
├── OnSuccess()
│   ├── Resolve(StreamBuffer)
│   └── TPromise<T> state → psFulfilled
├── OnError()
│   ├── Reject(error)
│   └── TPromise<T> state → psRejected
└── OnCancellation()
    └── Reject("Aborted")

   ↓ 

TPromise<T> Resolution
├── If resolved
│   └── Execute all .&Then() handlers
│       (via TThread.Queue → UI-safe)
├── If rejected
│   └── Execute all .&Catch() handlers
│       (also queued)

   ↓ 

Chaining continues
└── .&Then() → next logic
    (e.g., RunNextStep, SaveToFile, etc.)