> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 프로젝트

> 문서와 채팅을 하나의 공간으로 통합 관리하고 팀원에게 공유하는 프로젝트 기능

프로젝트는 **지식기반 + 채팅을 하나의 공간으로 묶은 개인 문서 관리 단위**입니다. 프로젝트를 선택하고 AI와 대화하면, 해당 프로젝트의 문서만을 참조하여 답변합니다. 팀원에게 프로젝트를 공유하면 독립적인 복사본이 생성되어 각자 자유롭게 활용할 수 있습니다.

***

## 프로젝트 vs 지식기반

| 구분        | 프로젝트            | 지식기반          |
| --------- | --------------- | ------------- |
| **목적**    | 개인/팀 문서 공간      | 에이전트용 지식 저장소  |
| **소유**    | 개인 소유, 복사 기반 공유 | 워크스페이스 공유     |
| **접근**    | 사이드바에서 바로 접근    | 에이전트에 연결하여 사용 |
| **채팅**    | 프로젝트 내 전용 채팅    | 에이전트 채팅에서 참조  |
| **내부 구조** | 자동 생성된 지식기반을 래핑 | 독립 엔티티        |

<Note>
  프로젝트는 문서를 내부 지식기반에 담지만, 이 지식기반은 워크스페이스의 **지식 기반** 목록에 나타나지 않습니다. 프로젝트 문서는 프로젝트 화면에서만 관리합니다.
</Note>

***

## 활용 사례

| 시나리오         | 설명                                              |
| ------------ | ----------------------------------------------- |
| **업무 문서 관리** | 프로젝트별 자료를 모아두고 AI에게 질문                          |
| **팀 협업**     | 부서 공용 문서를 프로젝트로 묶어 팀원과 공유                       |
| **리서치**      | 연구 자료를 정리하고 AI와 대화하며 분석                         |
| **고객 제안서**   | 고객별 요구사항 문서를 관리하고 AI로 초안 작성                     |
| **데이터 분석**   | CSV/Excel 파일을 업로드하고 AI가 Python 코드로 데이터 분석 및 시각화 |

***

## 프로젝트 목록

사이드바 하단의 **프로젝트** 섹션에서 내 프로젝트와 공유받은 프로젝트를 확인할 수 있습니다.

<Frame caption="프로젝트 목록에서 특정 프로젝트를 클릭하여 공유받은 프로젝트를 확인할 수 있습니다">
  <img src="https://mintcdn.com/cloocus/U5bh9kaxk4Ft7Sy6/images/collaboration/projects-detail.png?fit=max&auto=format&n=U5bh9kaxk4Ft7Sy6&q=85&s=733a87381e2e517e544ee63fe2322c7d" alt="프로젝트 상세 화면" width="2880" height="1800" data-path="images/collaboration/projects-detail.png" />
</Frame>

***

## 프로젝트 생성

<Steps>
  <Step title="새 프로젝트 만들기">
    사이드바의 프로젝트 섹션에 마우스를 올려, 우측의 **"+"** 버튼을 클릭합니다.

    <Frame caption="프로젝트 유형을 선택하고, 이름, 설명을 입력합니다.">
      <img src="https://mintcdn.com/cloocus/046evyIsgvOXyBMp/images/collaboration/projects-create-top.png?fit=max&auto=format&n=046evyIsgvOXyBMp&q=85&s=ce844b8b2c0a4a000f31279b4d8cab64" alt="프로젝트 생성 화면" width="1912" height="907" data-path="images/collaboration/projects-create-top.png" />
    </Frame>
  </Step>

  <Step title="기본 정보 입력">
    | 필드          | 설명              | 예시                 |
    | ----------- | --------------- | ------------------ |
    | **프로젝트 유형** | 일반 / 데이터 분석     | "일반" (기본값)         |
    | **이름**      | 프로젝트 표시 이름      | "2026 마케팅 전략"      |
    | **설명**      | 프로젝트 용도 설명 (선택) | "Q1 마케팅 캠페인 관련 자료" |

    <Note>
      **데이터 분석** 타입은 CSV/Excel 파일을 업로드하고 Python 코드로 분석하는 프로젝트입니다. 자세한 내용은 아래 [데이터 분석 프로젝트](#데이터-분석-프로젝트) 섹션을 참조하세요.
    </Note>
  </Step>

  <Step title="생성 완료">
    **"프로젝트 만들기"** 버튼을 클릭하면 프로젝트 상세 화면으로 자동 이동합니다.
  </Step>
</Steps>

***

## 파일 관리

### 파일 업로드

프로젝트 상세 화면의 **설정** 탭에서 파일을 업로드합니다. 업로드된 파일은 자동으로 벡터화되어 AI 검색이 가능해집니다.

<Frame caption="파일을 드래그 앤 드롭하거나 업로드 버튼으로 추가합니다">
  <img src="https://mintcdn.com/cloocus/046evyIsgvOXyBMp/images/collaboration/projects-upload.png?fit=max&auto=format&n=046evyIsgvOXyBMp&q=85&s=9745e4f52b53755f1f3bbea7b414bf74" alt="프로젝트 파일 업로드" width="1911" height="907" data-path="images/collaboration/projects-upload.png" />
</Frame>

<Tabs>
  <Tab title="드래그 앤 드롭">
    파일을 프로젝트 영역에 직접 끌어다 놓습니다.
  </Tab>

  <Tab title="파일 선택">
    업로드 버튼을 클릭하여 파일 선택 대화상자에서 파일을 선택합니다.
  </Tab>

  <Tab title="클라우드 스토리지">
    Google Drive, OneDrive, SharePoint에서 직접 파일을 가져올 수 있습니다 (관리자 설정 시).
  </Tab>
</Tabs>

**지원 파일 형식:**

| 카테고리       | 형식                                |
| ---------- | --------------------------------- |
| **문서**     | PDF, DOCX, PPTX, TXT, MD          |
| **스프레드시트** | XLSX, CSV                         |
| **기타**     | LibreOffice PDF 변환 활성화 시 추가 형식 지원 |

### 파일 목록

업로드된 파일은 프로젝트 상세 화면의 **설정** 탭 내 **프로젝트 파일** 섹션에서 확인할 수 있습니다.

| 정보      | 설명                         |
| ------- | -------------------------- |
| **파일명** | 업로드된 파일 이름                 |
| **크기**  | 파일 크기                      |
| **상태**  | 처리 상태 (업로드 중 / 처리 완료 / 오류) |

### 파일 삭제

파일 우측의 **X 버튼**을 클릭합니다. 삭제된 파일은 벡터 DB에서도 함께 제거됩니다.

<Warning>
  파일 삭제는 되돌릴 수 없습니다. 벡터 인덱스도 함께 삭제되므로 필요한 경우 원본 파일을 보관해두세요.
</Warning>

***

## 데이터 분석 프로젝트

<Info>
  **신규 기능** — 프로젝트 타입을 **데이터 분석**으로 선택하면, CSV/Excel 파일을 업로드하고 AI가 **Python 코드를 직접 실행**하여 데이터를 분석하고 차트를 생성합니다.
</Info>

### 일반 프로젝트와의 차이

|              | 일반 프로젝트                  | 데이터 분석 프로젝트                     |
| ------------ | ------------------------ | ------------------------------- |
| **파일 형식**    | PDF, DOCX, TXT 등 모든 문서   | CSV, XLSX, XLS, TSV, Parquet만   |
| **처리 방식**    | 텍스트 추출 → 청킹 → 벡터DB (RAG) | 메타데이터 추출 → Jupyter에 파일 마운트      |
| **AI 응답 방식** | 문서 검색 기반 답변              | Python 코드 실행 기반 답변              |
| **차트**       | 없음                       | Plotly 인터랙티브 차트, matplotlib 이미지 |
| **필수 환경**    | 없음                       | **Jupyter 서버** 연결 필요            |

### 사전 요구사항

<Warning>
  데이터 분석 프로젝트는 **Jupyter 서버가 연결되어 있어야** 사용할 수 있습니다. 관리자 > 설정 > 코드 실행에서 Jupyter 서버가 설정되어 있지 않으면 프로젝트 생성이 차단됩니다.
</Warning>

### 생성 및 사용

<Steps>
  <Step title="프로젝트 생성 시 '데이터 분석' 타입 선택">
    프로젝트 생성 화면에서 타입을 **데이터 분석**으로 선택합니다.
  </Step>

  <Step title="데이터 파일 업로드">
    CSV, Excel(XLSX/XLS), TSV, Parquet 파일을 업로드합니다. 업로드된 파일은 자동으로 Jupyter 환경에 마운트되며, 컬럼 정보 등 메타데이터가 추출됩니다.
  </Step>

  <Step title="AI에게 분석 요청">
    프로젝트를 선택하고 채팅에서 분석을 요청합니다. AI가 Python 코드를 자동으로 작성하고 실행하여 결과를 반환합니다.
  </Step>
</Steps>

### 분석 흐름

AI는 3단계 도구를 순차적으로 활용하여 데이터를 분석합니다.

```mermaid theme={null}
flowchart LR
    A[사용자 질문] --> B[1. 파일 메타데이터 조회]
    B --> C[2. 상세 데이터 확인]
    C --> D[3. Python 코드 실행]
    D --> E[분석 결과 + 차트]
```

|  단계 | 도구                     | 설명                                                       |
| :-: | ---------------------- | -------------------------------------------------------- |
|  1  | **data\_file\_info**   | 업로드된 파일 목록, 컬럼명, 데이터 타입 등 메타데이터 조회                       |
|  2  | **get\_file\_details** | 특정 파일의 상세 데이터 샘플 확인 (head, describe 등)                   |
|  3  | **code\_interpreter**  | Jupyter 커널에서 Python 코드 실행 (pandas, plotly, matplotlib 등) |

### 차트 생성

AI가 데이터 시각화를 요청받으면 **Plotly 인터랙티브 차트**를 생성합니다. 차트는 채팅 화면에서 직접 확인할 수 있으며, 확대/축소, 호버 정보 등 인터랙션이 가능합니다.

| 차트 라이브러리       |  지원 | 형태                    |
| -------------- | :-: | --------------------- |
| **Plotly**     |  기본 | 인터랙티브 차트 (확대, 호버, 필터) |
| **matplotlib** |  지원 | PNG 이미지로 표시           |

### 예시 대화

```
Q: 매출 데이터에서 월별 트렌드를 보여줘
A: 업로드된 sales_2025.csv 파일을 분석하겠습니다.

   [Code Interpreter 실행: pandas로 월별 집계 + Plotly 차트 생성]

   📊 월별 매출 트렌드입니다:
   [인터랙티브 차트]

   주요 발견:
   - 3월에 전월 대비 23% 상승
   - Q1 총 매출은 12.5M원
```

<Note>
  Jupyter 커널은 프로젝트별로 **영속적으로 유지**됩니다. 이전 대화에서 생성한 변수나 데이터프레임을 이후 대화에서 계속 사용할 수 있습니다. Jupyter 컨테이너가 재시작되면 파일이 자동으로 다시 마운트됩니다.
</Note>

***

## 프로젝트에서 채팅

### 프로젝트 컨텍스트 채팅

프로젝트를 선택한 상태에서 채팅을 시작하면, 해당 프로젝트의 문서만을 참조하여 AI가 답변합니다.

<Steps>
  <Step title="프로젝트 선택">
    사이드바에서 프로젝트를 클릭합니다.
  </Step>

  <Step title="질문 입력">
    채팅 입력창에 질문을 입력합니다. AI가 프로젝트 문서를 자동으로 검색합니다.
  </Step>

  <Step title="응답 확인">
    AI가 프로젝트 문서를 검색하여 출처와 함께 답변합니다.
  </Step>
</Steps>

<Frame caption="프로젝트를 선택하고 AI와 대화하면 해당 프로젝트 문서만 참조합니다">
  <img src="https://mintcdn.com/cloocus/U5bh9kaxk4Ft7Sy6/images/collaboration/projects-chat.png?fit=max&auto=format&n=U5bh9kaxk4Ft7Sy6&q=85&s=830d5b42c8889a267a468f12cb1bba51" alt="프로젝트 채팅" width="2880" height="1800" data-path="images/collaboration/projects-chat.png" />
</Frame>

**예시:**

```
Q: 이번 분기 마케팅 예산 계획은?
A: 프로젝트 문서를 확인한 결과, 이번 분기 마케팅 예산은...
   [출처: Q1_마케팅_계획.pdf, 12페이지]
```

### 채팅 관리

프로젝트 내에서 진행한 채팅은 프로젝트 상세 화면의 **채팅** 탭에서 확인할 수 있습니다.

| 정보        | 설명           |
| --------- | ------------ |
| **채팅 제목** | 자동 생성된 대화 제목 |
| **수정일**   | 마지막 대화 시간    |

<Tip>
  프로젝트 채팅은 메인 사이드바의 채팅 목록에 표시되지 않습니다. 프로젝트별로 분리되어 깔끔하게 관리됩니다.
</Tip>

***

## 프로젝트 공유

프로젝트를 다른 사용자에게 공유할 수 있습니다. 공유는 **복사 기반**으로 동작합니다.

<Steps>
  <Step title="설정 탭 이동">
    프로젝트 상세 화면에서 **설정** 탭으로 이동합니다.
  </Step>

  <Step title="공유 대상 선택">
    **"사용자에게 복사"** 섹션에서 사용자를 검색하고 선택합니다. 여러 명에게 동시에 공유할 수 있습니다.
  </Step>

  <Step title="공유 실행">
    **"사용자에게 복사"** 버튼을 클릭하면 선택한 사용자에게 프로젝트 복사본이 생성됩니다.
  </Step>
</Steps>

<Frame caption="복사 기반 공유 — 대상 사용자를 선택하고 사용자에게 복사를 클릭합니다">
  <img src="https://mintcdn.com/cloocus/KaBbk3O9rWexEgxk/images/collaboration/projects-share.png?fit=max&auto=format&n=KaBbk3O9rWexEgxk&q=85&s=b0fa937666fc5e3094f4812dba3193a1" alt="사용자에게 복사" width="1911" height="905" data-path="images/collaboration/projects-share.png" />
</Frame>

<Frame caption="공유받은 사용자에게는 '(소유자에게서 복사됨)' 표시와 함께 독립 복사본이 생성됩니다">
  <img src="https://mintcdn.com/cloocus/KaBbk3O9rWexEgxk/images/collaboration/projects-share-received.png?fit=max&auto=format&n=KaBbk3O9rWexEgxk&q=85&s=9e446584e46702a6240bd234ae47ec60" alt="공유받은 프로젝트 복사본" width="1909" height="905" data-path="images/collaboration/projects-share-received.png" />
</Frame>

### 공유 특성

| 항목         | 설명                                               |
| ---------- | ------------------------------------------------ |
| **독립 복사본** | 공유받은 사용자에게 별도의 프로젝트가 생성됩니다                       |
| **파일 복사**  | 원본 프로젝트의 파일이 벡터 재인덱싱과 함께 복사됩니다                   |
| **독립 수정**  | 공유 후 각 사용자가 자신의 프로젝트를 자유롭게 수정할 수 있습니다            |
| **출처 추적**  | 복사본의 메타데이터에 원본 프로젝트 정보(소유자, 프로젝트명, 복사 시간)가 기록됩니다 |

<Note>
  공유는 일회성 복사입니다. 원본 프로젝트를 수정해도 공유받은 복사본에는 반영되지 않습니다. 실시간 동기화가 필요한 경우 워크스페이스 지식기반의 접근 권한 공유를 사용하세요.
</Note>

***

## 프로젝트 설정

프로젝트 상세 화면의 **설정** 탭에서 프로젝트 정보를 수정할 수 있습니다.

<Frame caption="프로젝트 설정에서 이름, 설명을 수정하거나 프로젝트를 삭제합니다">
  <img src="https://mintcdn.com/cloocus/U5bh9kaxk4Ft7Sy6/images/collaboration/projects-settings.png?fit=max&auto=format&n=U5bh9kaxk4Ft7Sy6&q=85&s=420b0a22fbf5892ef6a65912b909cb84" alt="프로젝트 설정" width="2880" height="1800" data-path="images/collaboration/projects-settings.png" />
</Frame>

| 항목           | 설명                           |
| ------------ | ---------------------------- |
| **이름**       | 프로젝트 이름 변경                   |
| **프로젝트 파일**  | 프로젝트에 연결된 파일 목록 관리 및 업로드     |
| **기본 모델**    | 프로젝트 채팅에서 사용할 기본 AI 모델 선택    |
| **프로젝트 지침**  | AI에게 전달할 프로젝트 전용 시스템 프롬프트 설정 |
| **사용자에게 복사** | 선택한 사용자에게 프로젝트 복사본 공유        |
| **삭제**       | 프로젝트 및 연결된 모든 리소스 영구 삭제      |

***

## 프로젝트 삭제

프로젝트를 삭제하면 연결된 모든 리소스가 함께 삭제됩니다.

<Warning>
  프로젝트 삭제 시 다음 항목이 모두 영구 삭제됩니다:

  * 프로젝트 본체
  * 연결된 지식기반 및 벡터 인덱스
  * 프로젝트 내 모든 채팅 기록

  삭제된 프로젝트는 복구할 수 없습니다. 공유받은 사용자의 복사본에는 영향을 주지 않습니다.
</Warning>

***

## FAQ

<Accordion title="프로젝트에 파일 수 제한이 있나요?">
  시스템 설정에 따라 다릅니다. 일반적으로 파일 수 제한은 없지만, 파일 크기 제한은 관리자 설정을 따릅니다.
</Accordion>

<Accordion title="프로젝트를 공유하면 실시간으로 동기화되나요?">
  아니요, 공유 시 독립 복사본이 생성됩니다. 원본을 수정해도 공유받은 프로젝트에는 반영되지 않습니다. 실시간 공유가 필요하면 워크스페이스 지식기반의 접근 권한을 활용하세요.
</Accordion>

<Accordion title="기존 지식기반을 프로젝트로 변환할 수 있나요?">
  직접 변환은 불가합니다. 프로젝트를 생성한 후 파일을 다시 업로드하세요.
</Accordion>

<Accordion title="프로젝트 채팅은 일반 채팅 목록에 나타나나요?">
  아니요, 프로젝트 채팅은 프로젝트 상세 화면의 채팅 탭에서만 표시됩니다. 메인 사이드바의 채팅 목록과 분리되어 깔끔하게 관리됩니다.
</Accordion>

<Accordion title="공유받은 프로젝트의 원본 정보를 확인할 수 있나요?">
  네, 공유받은 프로젝트의 메타데이터에 원본 소유자, 프로젝트명, 복사 시간이 기록되어 있습니다.
</Accordion>

<Accordion title="데이터 분석 프로젝트에서 지원하는 파일 형식은?">
  **CSV, XLSX, XLS, TSV, Parquet** 파일만 업로드할 수 있습니다. PDF나 DOCX 등 문서 파일은 일반 프로젝트를 사용하세요.
</Accordion>

<Accordion title="데이터 분석 프로젝트를 사용하려면 어떤 환경이 필요한가요?">
  관리자가 **Jupyter 서버**를 연결해야 합니다. 관리자 > 설정 > 코드 실행에서 Jupyter 서버 URL이 설정되어 있어야 프로젝트 생성이 가능합니다. Jupyter가 미설정 상태에서 데이터 분석 타입을 선택하면 안내 메시지가 표시됩니다.
</Accordion>

<Accordion title="데이터 분석에서 이전 대화의 변수를 다시 사용할 수 있나요?">
  네, Jupyter 커널이 프로젝트별로 유지되므로 이전 대화에서 생성한 변수나 데이터프레임을 이후 대화에서 계속 사용할 수 있습니다.
</Accordion>