# dfinke/psai architecture

> Architecture diagram of the GitHub repository dfinke/psai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dfinke/psai
- Repository: https://github.com/dfinke/psai

## Overview

##### Main system components
- User Interface Layer: This is the PowerShell console (or any script/file that the user runs) where commands like Invoke-OAIChat or Invoke-QuickPrompt are executed.
- PSAI Module Core: The heart of the system is the PSAI engine implemented mainly with public functions (in the Public directory). This layer exposes functions for interacting with OpenAI via different commands (e.g., New-Agent, Get-AgentResponse, ConvertTo-AIPrompt).
- Internal Helper and Utility Components: The Private folder contains helper scripts that support core functionality such as argument completion, constructing multipart data, and HTTP calls (like Invoke-OAIBeta).
- Tools Integration: Under Public/Tools (and additional functions elsewhere) you have multiple specialized tools (like CalculatorTool, StockTickerTool, YouTubeTool, etc.) which are registered and used by agents. Represent these as separate modules that plug into the overall agent workflow.

##### Relationships and Data Flow
- The PSAI core then delegates tasks to internal helper scripts (Private folder) and further relies on the Agents Manager to decide which specialized tool should be engaged.
- The ConvertTo-AIPrompt functionality is another component that takes a repository as input and reformats the content for AI processing. This can be an independent utility module represented within the core PSAI engine.
- Unit and integration tests (represented by the __tests__ folder) should be indicated as a separate “Testing Suite” element verifying interactions between these components.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly delineate the client interface, internal processing (script logic and agents), and the adapter/connector layer that communicates with external services.
- Modularity and Extensibility: Emphasize how new tools (agents and integrations) can be registered and added. Use annotations such as “Tool Registration” or “Modular Plugin Architecture.”
- Separation of Concerns: The distinction between Public and Private functions illustrates a clear separation of API exposure versus internal logic.

##### Relevant Technologies, Frameworks, and Languages
- PowerShell as the primary development environment.
- OpenAI and Azure OpenAI APIs (with secrets management for API keys).
- Use of GitHub Actions (configuration in .github/workflows/ci.yml) which may be depicted as a CI/CD pipeline node connected to the source repository.
- Testing tools (Pester-based tests in the __tests__ directory).

##### Elements
- From the user invoking a command to the PSAI module.
- From the module to the Agents Manager and then to registered tools.
- From the tools to external services.
- Adding a layer for “Configuration & Secret Management” where API keys and secrets (e.g., OpenAIKey, TAVILY_API_KEY) are set up.

##### Additional Details
- You might include a smaller “Utility” cluster that houses functions like ConvertFrom/To functions—demonstrating how source code and prompts are formatted.
- A CI/CD integration block (based on GitHub Actions) that shows automated testing and deployment pipelines.
- Detail any special flows like “Agent Tool Registration” showing that new tools (like from Public/Tools) can plug into the agent workflow to extend PSAI’s capabilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        UI["PowerShell Console/Script Commands"]:::user
    end

    subgraph "PSAI Module Core"
        Core["PSAI Module Core"]:::internal
        PromptUtil["ConvertTo-AIPrompt Utility"]:::internal
    end

    subgraph "Internal Helper Components"
        Helpers["Internal Helper & Utility Components"]:::internal
    end

    subgraph "Autonomous Agents Subsystem"
        Agents["Agents Manager"]:::internal
    end

    subgraph "Tools Integration Modules"
        Tool1["CalculatorTool"]:::tool
        Tool2["StockTickerTool"]:::tool
        Tool3["TavilyTool"]:::tool
        Tool4["YouTubeAssistant"]:::tool
        Tool5["YouTubeTool"]:::tool
    end

    subgraph "External APIs & Services"
        OpenAI["OpenAI API"]:::external
        Azure["Azure OpenAI API"]:::external
        ThirdParty["Third-Party Services"]:::external
    end

    subgraph "Testing & CI/CD"
        Testing["Testing Suite"]:::cd
        CI["CI/CD Pipeline"]:::cd
    end

    UI -->|"invokes"| Core
    Core -->|"calls"| Helpers
    Core -->|"formatsPrompt"| PromptUtil
    Core -->|"managesAgents"| Agents
    Agents -->|"usesTool"| Tool1
    Agents -->|"usesTool"| Tool2
    Agents -->|"usesTool"| Tool3
    Agents -->|"usesTool"| Tool4
    Agents -->|"usesTool"| Tool5
    Tool1 -->|"callsAPI"| OpenAI
    Tool1 -->|"callsAPI"| Azure
    Tool2 -->|"callsAPI"| ThirdParty
    Tool3 -->|"callsAPI"| ThirdParty
    Tool4 -->|"callsAPI"| OpenAI
    Tool5 -->|"callsAPI"| OpenAI
    CI -->|"runsTests"| Testing
    Testing -->|"verifies"| Core

    %% Click Events
    click UI "https://github.com/dfinke/psai/blob/main/Public/Invoke-OAIChat.ps1"
    click Core "https://github.com/dfinke/psai/blob/main/PSAI.psm1"
    click PromptUtil "https://github.com/dfinke/psai/blob/main/Public/ConvertTo-AIPrompt.ps1"
    click Helpers "https://github.com/dfinke/psai/blob/main/Private/ArgumentCompletion.ps1"
    click Agents "https://github.com/dfinke/psai/blob/main/Public/New-Agent.ps1"
    click Tool1 "https://github.com/dfinke/psai/tree/main/Public/Tools"
    click Tool2 "https://github.com/dfinke/psai/tree/main/Public/Tools"
    click Tool3 "https://github.com/dfinke/psai/tree/main/Public/Tools"
    click Tool4 "https://github.com/dfinke/psai/tree/main/Public/Tools"
    click Tool5 "https://github.com/dfinke/psai/tree/main/Public/Tools"
    click Testing "https://github.com/dfinke/psai/tree/main/__tests__"
    click CI "https://github.com/dfinke/psai/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef user fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef internal fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef tool fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef cd fill:#d1ecf1,stroke:#333,stroke-width:2px;
```
