<br>

- 스트리밍 예제 (SSE):

```pascal
//uses GenAI, GenAI.Types;

var Client: IGenAI;
...

<br>

___ 

Summary
- [Introduction](#introduction)
- [Philosophy and Scope](#philosophy-and-scope)
- [Documentation](#documentation)
- [Responses vs. Chat Completions](#responses-vs-chat-completions)
- [Functional Demo](#functional-demo)
- [Functional coverage](#functional-coverage)
- [Tips and tricks](#tips-and-tricks)
- [2.0.0에서 제거됨](#removed-in-200)
- [기여하기 (Contributing)](#contributing)
- [라이선스 (License)](#license)

___ 

<br>

## Introduction

> **Delphi 12 Community Edition** (v12.1 Patch 1)으로 구축됨
>이 Wrapper 자체는 MIT 라이선스를 따릅니다.
>Delphi CE로 무료로 컴파일하고 테스트할 수 있으며, 최근 상용 Delphi 에디션도 동일하게 작동합니다.

<br>

**DelphiGenAI**는 Delphi를 위한 완전한 OpenAI 래퍼(wrapper)로, 텍스트, 비전, 오디오, 이미지 생성, 임베딩, 대화, 컨테이너, 그리고 최신 `v1/responses` 에이전트 워크플로우까지 전체 플랫폼을 포괄합니다. 이는 동기/비동기/await 지원을 주요 Delphi 플랫폼 전반에 걸쳐 제공하는 통합 인터페이스를 제공하여, Delphi 애플리케이션에서 현대적인 멀티모달 및 도구 기반 AI 기능을 쉽게 활용할 수 있게 합니다.

<br>

> [!IMPORTANT]
> 
이것은 비공식 라이브러리입니다. **OpenAI**는 `Delphi`를 위한 공식 라이브러리를 제공하지 않습니다.
> 이 저장소는 [OpenAI](https://openai.com/) 공개 API를 기반으로 한 `Delphi` 구현을 담고 있습니다.

<br>

>[!TIP]
> 비동기 메서드를 사용할 때, 가능한 가장 넓은 범위의 스코프(scope)로 `IGenAI` 클라이언트를 선언하세요. 이상적으로는 애플리케이션의 `OnCreate`에서 하는 것이 좋습니다.

<br>

___ 

## 철학 및 범위 (Philosophy and Scope)

OpenAI는 상호 보완적인 두 가지 텍스트 표면(text surfaces)을 노출합니다:
- **Chat Completions API** (`v1/chat/completions`) — 확립된 단일 호출 채팅 인터페이스;
- **Responses API** (`v1/responses`) — 동일한 아이디어 위에 내장 도구 및 상태 관리를 추가하는 새로운 에이전트 원시 요소(agentic primitive)로, Chat Completions을 점진적으로 대체할 목적으로 설계되었습니다.

그 주위에는 나머지 플랫폼들, 즉 오디오, 이미지, 임베딩, 파일, 벡터 스토어, 배치, 파인튜닝 (fine-tuning), 모더레이션 (moderation), 컨테이너, 스킬(skills), 대화, 그리고 실시간 기능이 자리하고 있습니다.

DelphiGenAI는 설계상 **OpenAI API를 엄격하게 일대일로 매핑**합니다. 따라서 제공업체(provider)별 확장 기능, 폴백(fallbacks), 또는 공급자 표면 위에 추가되는 행동 적응을 도입하지 않습니다. 이 시스템의 목표는 다음과 같습니다:
- 지원되는 모든 엔드포인트와 파라미터에 대한 **충실한 매핑**;
- JSON 우선 사용이 아닌, **Delphi 중심의 인체공학적 설계** (유창한 빌더, 강력하게 타입 지정된 결과);
- 엔드포인트 전반에 걸친 **통일된 실행 모델** (동기식(synchronous), 비동기식(asynchronous) 및 promise 기반);
- OpenAI가 아닌 공급업체와의 **명확한 경계 설정**. 이들 공급업체는 OpenAI와 호환되는 표면을 노출하는 경우에만 접근 가능합니다 (참고: [Provider Support](guides/Provider-Support-and-OpenAI-API.md)).

### 핵심 실행 모드

- **표준 생성(Standard generation)** — 블로킹 방식 또는 promise 기반; 전체 응답이 한 번에 반환됩니다. 백그라운드 또는 배치 워크플로우에 적합합니다.
- **SSE 스트리밍(SSE streaming)** — 동기식 또는 비동기식이며, 세션 레벨(청크별) 또는 이벤트 레벨(타입 지정된 이벤트별) 콜백을 통해 응답 스트림을 정밀하게 가로챌 수 있습니다.
- **도구 기반 및 에이전트 워크플로우(Tool-driven & agentic workflows)** — 엄격한 스키마 검증과 함께 함수 호출 및 내장 도구(웹 검색, 파일 검색, 코드 인터프리터, 이미지 생성, 원격 MCP, 셸, 패치 적용, 기술)를 지원하며, 이를 뒷받침하는 에이전트 기능 구조: 코드 인터프리터 **컨테이너**와 자동 컨텍스트 **압축(compaction)**.
- **다중 공급업체(Multiple providers)** — 동일한 `IGenAI` 클라이언트가 OpenAI, 로컬 LM Studio 서버, Google Gemini 또는 모든 OpenAI 호환 엔드포인트를 대상으로 합니다.

이러한 구분은 API 수준과 문서에서 일관되게 적용됩니다.

<br>

___ 

## 문서(Documentation)

문서는 **집중적인 Markdown 가이드** 형태로 구성되어 있으며, 각 가이드는 하나의 기능을 다룹니다. 이들은 모두 단일 진입점에서 나열되고 설명되며 순서가 지정됩니다:

- **[문서 색인 — `guides/guides.md`](guides/guides.md#guides)** — 여기서 시작하세요.
- [Changelog](Changelog.md#2026-june-9-version-200)
- [이 프로젝트 소개](guides/GenAI.md#about-this-project)

각 가이드는 raw JSON이 아닌 Delphi 우선 예제(동기식, 비동기식 및 promise 기반)를 제공합니다.

---

## 응답(Responses) 대 채팅 완성(Chat Completions)

`v1/responses` API는 새로운 핵심 API입니다. 이는 채팅 완성이 가진 단순성에 내장 도구(웹 검색, 파일 검색, 컴퓨터 사용, 이미지 생성, 원격 MCP, 코드 인터프리터, 스킬, 컨테이너)를 결합한 에이전트적 프리미티브(agentic primitive)입니다. 이 API는 `v1/chat/completions`을 점진적으로 대체할 목적으로 설계되었습니다.

>[!NOTE]
>새로운 사용자라면 **Responses API**를 권장합니다.

| 기능 | [Chat Completions](guides/ChatCompletion.md#chat-completion) | [Responses](guides/Responses.md#responses) |
|:---|:---:|:---:|
| 텍스트 생성 | ● | ● |
| ... | | |
>[!WARNING]
> [OpenAI의 참고 사항](https://platform.openai.com/docs/guides/responses-vs-chat-completions#the-chat-completions-api-is-not-going-away) <br>
> Chat Completions API는 AI 애플리케이션 구축을 위한 업계 표준이며, 우리는 이를 무기한으로 계속 지원할 계획입니다. Responses API는 도구 사용, 코드 실행 및 상태 관리가 관련된 워크플로우를 단순화합니다.

---

## 기능 데모(Functional Demo)

이 저장소에는 [demos](demos) 폴더에 작업 가능한 **FMX** 데모가 포함되어 있으며, 이는 Pythia-WebView2([https://github.com/MaxiDonkey/Pythia-webView2](https://github.com/MaxiDonkey/Pythia-webView2))를 기반으로 구축되었고, 여기서 래퍼의 호스트 애플리케이션으로 사용됩니다.

이 데모는 **DelphiGenAI가 고립된 코드 스니펫을 통해서뿐만 아니라 실제 애플리케이션 흐름 내부에서 실행되는 것**을 보여주기 때문에 사용자에게 중요합니다. 이는 `IGenAI` 클라이언트가 **Responses API**를 통해 UI 지향적인 대화 계층에 연결되어 있으며, 비동기 SSE 스트리밍, 요청/응답 JSON 추적성, 함수/MCP/스킬/에이전트 카드, 이미지 생성 및 편집(Images API), Files API를 통한 파일 업로드, 검색을 위한 벡터 스토어 지식 색인화(RAG), 그리고 Whisper 음성-텍스트 변환을 이용한 마이크 녹음을 시연합니다.

데모의 핵심 부분 중 하나는 컨텍스트 재구축 레이어(`Demo.OpenAI.Context.pas`)입니다. 이 레이어는 별도의 Conversations API에 의존하지 않으면서 데모가 필요로 하는 두 가지 연속성 전략을 제공합니다. 첫째는 **로컬 컨텍스트 재구축**으로, Delphi가 저장된 JSON 요청과 스트리밍되는 JSON 응답(텍스트 블록, 추론 블록, 도구 호출 및 일치하는 도구 결과, MCP 교환, 웹 검색 결과)으로부터 더 풍부한 메시지 컨텍스트를 재구성하며 이전에 사용했던 도구를 고려합니다. 둘째는 `previous_response_id`를 통한 **클라우드 체이닝**으로, OpenAI가 대화 상태를 서버 측에 유지합니다. 두 기능 모두 기본적으로 비활성화되어 있어, 명시적으로 옵트인하지 않는 한 OpenAI 서버에는 아무것도 보존되지 않습니다.

가이드들은 교육적인 경로를 유지하고 있습니다. 각 API 서피스(surface)는 독립적으로 설명되며, 초점을 맞춘 Delphi 예제를 제공합니다. 데모는 보완적인 참고 자료 역할을 합니다. 이 데모는 해당 기능들이 실제 작동하는 Delphi 애플리케이션에서 엔드투엔드로 어떻게 협력하는지 보여주며, API 키 검증, 런타임 설정 및 선택적 MCP/스킬/에이전트 구성을 위한 실질적인 시작점을 제공합니다.

**SDK가 Pythia에 플러그인되는 방법**—통합 계약, `IGenAI` ↔ Pythia 이벤트 흐름, 턴 라우팅, 비동기 서비스(async services), 다중 턴 컨텍스트 및 `delphi-uses-graph` 사용자 정의 스킬에 대한 전체 단계별 설명은 전용 워크스루: **[`demos/docs/FMX_OpenAI.md`](demos/docs/FMX_OpenAI.md)**를 참조하십시오. 또한 [demos/README.md](demos/README.md)에서 데모별 설정 참고 사항을 확인하십시오.

<br>

___ 

## 기능 커버리지 (Functional coverage)

GenAI가 지원하는 OpenAI 엔드포인트입니다. 각 엔드포인트에 대한 매칭 가이드는 **[문서화 인덱스](guides/guides.md)**를 참조하십시오.

| Endpoint | Supported | Status / notes |
|--- |:---: |:---: |
| /audio/speech | <div align="center"><span style="color: green;">●</span></div> | ![updated](https://img.shields.io/badge/UPDATED-003399?style=flat) |
| ... |

버전 ***1.0.1의 GenAI***부터 `GenAI.Monitoring` 유닛은 **진행 중인 HTTP 요청을 모니터링하는 역할을 담당합니다.**

`Monitoring` 인터페이스는 `uses` 절에 `GenAI.Monitoring` 유닛을 포함하여 접근할 수 있습니다.
대안으로, `GenAI` 유닛에 선언된 `HttpMonitoring` 함수를 통해 접근할 수도 있습니다.

**사용 예시**

```pascal
//uses GenAI;

procedure TForm1.FormCloseQuery(Sender: TObject; var CanClose: Boolean);
...