From 502dd4bbdd1f4f63721943b24e4e2d388700601f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9C=A4=EC=98=88=EB=A6=BC?= Date: Thu, 13 Aug 2026 19:06:39 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20readme=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 327 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 194 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index 52762ea..ac0a9a8 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ -# 🧠 Tryna Brain +# 🧠 tryna brain -> 일정을 μ΄ν•΄ν•˜κ³ , λ§₯락을 μ—°κ²°ν•˜λ©°, ν•„μš”ν•œ μ€€λΉ„λ₯Ό μΆ”μ²œν•˜λŠ” FastAPI 기반 Context Intelligence Engine. +> 일정을 μ΄ν•΄ν•˜κ³  λ§₯락을 μ—°κ²°ν•΄ ν•„μš”ν•œ μ€€λΉ„Β·μ‹€ν–‰ ν•­λͺ©μ„ μΆ”μ²œν•˜λŠ” FastAPI 기반 뢄석 μ„œλ²„ -Tryna Brain은 TRYNA μ„œλΉ„μŠ€μ˜ 뢄석/μΆ”μ²œ μ „μš© μ„œλ²„μž…λ‹ˆλ‹€. κΈ°μ‘΄ README의 λ°©ν–₯처럼 μžμ—°μ–΄ 일정 뢄석, Neo4j 지식 κ·Έλž˜ν”„ 쑰회, LLM 기반 μΆ”μ²œ μ •μ œλ₯Ό λ‹΄λ‹Ήν•˜λ˜, Spring Server와 역할을 λΆ„λ¦¬ν•˜μ—¬ 독립적인 FastAPI μ„œλ²„λ‘œ μš΄μ˜ν•˜λŠ” 것을 λͺ©ν‘œλ‘œ ν•©λ‹ˆλ‹€. +tryna brain은 tryna μ„œλΉ„μŠ€μ˜ 일정 νŒŒμ‹± 및 μΆ”μ²œ μ „μš© μ„œλ²„μž…λ‹ˆλ‹€. Spring μ„œλ²„μ™€ 역할을 λΆ„λ¦¬ν•˜μ—¬ μžμ—°μ–΄ 일정 νŒŒμ‹±, Neo4j 기반 의미 맀핑과 후보 쑰회, Upstage 기반 μž„λ² λ”© 및 μΆ”μ²œ 문ꡬ μ •μ œλ₯Ό λ‹΄λ‹Ήν•©λ‹ˆλ‹€. --- ## πŸ“Œ μ†Œκ°œ -TRYNAλŠ” μ‚¬μš©μžκ°€ μž…λ ₯ν•œ 짧은 일정 속 λ§₯락을 μ΄ν•΄ν•˜κ³ , 일정 전후에 μ‹€μ œλ‘œ ν•„μš”ν•œ ν•  일을 μ œμ•ˆν•˜λŠ” 일정 관리 μ„œλΉ„μŠ€μž…λ‹ˆλ‹€. +trynaλŠ” μ‚¬μš©μžκ°€ μž…λ ₯ν•œ 짧은 μΌμ •μ˜ λ§₯락을 μ΄ν•΄ν•˜κ³ , 일정 전후에 ν•„μš”ν•œ ν•  일을 μ œμ•ˆν•˜λŠ” 일정 μ„œλΉ„μŠ€μž…λ‹ˆλ‹€. -Tryna Brain은 이 μ€‘μ—μ„œ **일정 λ¬Έμž₯ 이해, λ§₯락 ꡬ쑰화, 관계 기반 μΆ”μ²œ 후보 쑰회, LLM 기반 후보 μ •μ œ**λ₯Ό λ‹΄λ‹Ήν•˜λŠ” 뢄석/μΆ”μ²œ μ—”μ§„μž…λ‹ˆλ‹€. +tryna brain은 λ‹€μŒ 두 κΈ°λŠ₯을 μ œκ³΅ν•©λ‹ˆλ‹€. + +- μžμ—°μ–΄ μΌμ •μ—μ„œ λ‚ μ§œ, μ‹œκ°„, μž₯μ†Œ λ“± 일정 후보 정보 μΆ”μΆœ +- 일정 μœ ν˜•Β·λ§₯락·μž₯μ†Œλ₯Ό λΆ„μ„ν•˜μ—¬ μ€€λΉ„ 및 μ‹€ν–‰ ν•­λͺ© μΆ”μ²œ 예λ₯Ό λ“€μ–΄ μ‚¬μš©μžκ°€ λ‹€μŒκ³Ό 같이 μž…λ ₯ν•˜λ©΄: @@ -18,50 +21,54 @@ Tryna Brain은 이 μ€‘μ—μ„œ **일정 λ¬Έμž₯ 이해, λ§₯락 ꡬ쑰화, 관계 κΈˆμš”μΌ 3μ‹œ νŒ€ν”Œ 회의 ``` -Brain μ„œλ²„λŠ” 후속 κ΅¬ν˜„μ—μ„œ λ‹€μŒκ³Ό 같은 정보λ₯Ό λΆ„μ„ν•˜κ³  μΆ”μ²œ 후보λ₯Ό μƒμ„±ν•©λ‹ˆλ‹€. +νŒŒμ‹± APIλŠ” λ‹€μŒκ³Ό 같이 일정 후보 정보λ₯Ό λ°˜ν™˜ν•©λ‹ˆλ‹€. ```json { - "sourceText": "κΈˆμš”μΌ 3μ‹œ νŒ€ν”Œ 회의", - "titleCandidate": "νŒ€ν”Œ 회의", - "dateCandidate": "이번 μ£Ό κΈˆμš”μΌ", - "timeCandidate": "15:00", + "tempEventId": "tmp_f7258568-0374-4710-8473-329576255448", + "eventTitle": "κΈˆμš”μΌ 3μ‹œ νŒ€ν”Œ 회의", + "draftRevision": 1, + "startDate": "2026-08-14", + "dateSource": "RELATIVE_EXPRESSION", + "startTime": "15:00:00", "placeCandidate": null, - "eventTypeCandidate": "meeting" + "toEmbedding": ["νŒ€ν”Œ", "회의"], + "isAllDayCandidate": false, + "needsConfirmation": false, + "warnings": [] } ``` -이후 Neo4j와 Upstage LLM을 ν™œμš©ν•΄ 회의 μ•ˆκ±΄ 정리, 곡유 자료 확인, μž₯μ†Œ 확인 같은 μ€€λΉ„/μ‹€ν–‰ ν•­λͺ© 후보λ₯Ό μ œμ•ˆν•˜λŠ” λ°©ν–₯으둜 ν™•μž₯ν•©λ‹ˆλ‹€. +이후 μΆ”μ²œ APIλŠ” Neo4j 관계·벑터 후보와 Upstage LLM을 ν™œμš©ν•˜μ—¬ `회의 μ‹œκ°„ 확인`, `μ–˜κΈ°ν•  λ‚΄μš© 정리`와 같은 μ€€λΉ„Β·μ‹€ν–‰ ν•­λͺ©μ„ μ΅œλŒ€ 3κ°œκΉŒμ§€ μ œμ•ˆν•©λ‹ˆλ‹€. --- ## 🧩 Server Responsibility -TRYNA λ°±μ—”λ“œλŠ” 역할에 따라 Spring Server와 FastAPI Brain Server둜 λΆ„λ¦¬ν•©λ‹ˆλ‹€. +tryna λ°±μ—”λ“œλŠ” 역할에 따라 Spring μ„œλ²„μ™€ FastAPI brain μ„œλ²„λ‘œ λΆ„λ¦¬ν•©λ‹ˆλ‹€. ### Spring Server -Spring ServerλŠ” μ„œλΉ„μŠ€ μš΄μ˜μ— ν•„μš”ν•œ 핡심 λ°±μ—”λ“œ κΈ°λŠ₯을 λ‹΄λ‹Ήν•©λ‹ˆλ‹€. +Spring μ„œλ²„λŠ” μ„œλΉ„μŠ€ μš΄μ˜μ— ν•„μš”ν•œ 핡심 λ°±μ—”λ“œ κΈ°λŠ₯을 λ‹΄λ‹Ήν•©λ‹ˆλ‹€. -- νšŒμ›/λΉ„νšŒμ› 인증 -- μ‚¬μš©μž 계정 관리 -- 일정 CRUD -- μΊ˜λ¦°λ” 쑰회 +- νšŒμ›/λΉ„νšŒμ› 인증 및 μ‚¬μš©μž 계정 관리 +- 일정 CRUD 및 μΊ˜λ¦°λ” 쑰회 +- μΆ”μ²œ μš”μ²­ 쀑 μ΅œμ‹  `draftRevision` 등둝 - μΆ”μ²œ κ²°κ³Ό μ €μž₯ - μ•Œλ¦Ό 및 μ™ΈλΆ€ μΊ˜λ¦°λ” 연동 - DB νŠΈλžœμž­μ…˜ 및 κΆŒν•œ 검증 ### FastAPI Brain Server -FastAPI Brain ServerλŠ” 일정 λ¬Έμž₯을 μ΄ν•΄ν•˜κ³  μΆ”μ²œ 후보λ₯Ό μƒμ„±Β·μ •μ œν•˜λŠ” 뢄석/μΆ”μ²œ 엔진 역할을 λ‹΄λ‹Ήν•©λ‹ˆλ‹€. +FastAPI brain μ„œλ²„λŠ” 일정 λ¬Έμž₯을 μ΄ν•΄ν•˜κ³  μΆ”μ²œ 후보λ₯Ό μƒμ„±Β·μ •μ œν•˜λŠ” 뢄석 엔진 역할을 λ‹΄λ‹Ήν•©λ‹ˆλ‹€. -- μžμ—°μ–΄ 일정 1μ°¨ νŒŒμ‹± -- Kiwi 기반 ν•œκ΅­μ–΄ ν˜•νƒœμ†Œ 뢄석 보쑰 -- Rule Based Parser 기반 일정 후보 ꡬ쑰화 -- Neo4j 기반 μΆ”μ²œ 후보 쑰회 -- Upstage LLM 기반 μΆ”μ²œ 후보 μ •μ œ -- μ‹œκ°„ν˜•/λΉ„μ‹œκ°„ν˜• λΆ„λ₯˜ 및 μΆ”μ²œ 개수 μ œν•œ -- Spring Server에 뢄석/μΆ”μ²œ κ²°κ³Ό λ°˜ν™˜ +- Rule Based Parser와 Kiwi 기반 μžμ—°μ–΄ 일정 νŒŒμ‹± +- Upstage μž„λ² λ”© 기반 일정 μœ ν˜•Β·λ§₯락·μž₯μ†Œ 의미 맀핑 +- Neo4j 관계 및 벑터 기반 μΆ”μ²œ 후보 쑰회 +- Upstage LLM 기반 μΆ”μ²œ ν•­λͺ© 선택 및 `displayText` μ •μ œ +- μ‹œκ°„ λ§₯락 검증과 `TIMED_ACTION`Β·`UNTIMED_PREP` λΆ„λ₯˜ +- Redis 기반 μ΅œμ‹  `draftRevision` 검증 +- Spring μ„œλ²„μ— νŒŒμ‹± 및 μΆ”μ²œ κ²°κ³Ό λ°˜ν™˜ --- @@ -71,10 +78,11 @@ FastAPI Brain ServerλŠ” 일정 λ¬Έμž₯을 μ΄ν•΄ν•˜κ³  μΆ”μ²œ 후보λ₯Ό 생성· | Type | Tool | | :--------------: | :---: | -| Language | ![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white) | +| Language | ![Python](https://img.shields.io/badge/Python_3.13-3776AB?style=for-the-badge&logo=python&logoColor=white) | | Framework | ![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white) | | ASGI Server | ![Uvicorn](https://img.shields.io/badge/Uvicorn-499848?style=for-the-badge) | | Database | ![Neo4j](https://img.shields.io/badge/Neo4j-4581C3?style=for-the-badge&logo=neo4j&logoColor=white) | +| Cache | ![Redis](https://img.shields.io/badge/Redis%2FValkey-FF4438?style=for-the-badge&logo=redis&logoColor=white) | | LLM | ![Upstage](https://img.shields.io/badge/Upstage_Solar-000000?style=for-the-badge) | | NLP | ![Kiwi](https://img.shields.io/badge/Kiwi_NLP-4CAF50?style=for-the-badge) | | Configuration | ![pydantic-settings](https://img.shields.io/badge/pydantic--settings-E92063?style=for-the-badge) ![python-dotenv](https://img.shields.io/badge/python--dotenv-ECD53F?style=for-the-badge) | @@ -94,18 +102,21 @@ Client β–Ό Spring Server β”‚ - β”‚ 일정 뢄석/μΆ”μ²œ μš”μ²­ + β”‚ λ‚΄λΆ€ API 인증 및 일정 νŒŒμ‹±/μΆ”μ²œ μš”μ²­ β–Ό FastAPI Brain Server β”‚ β”œβ”€β”€ Rule Based Parser + Kiwi - β”‚ 일정 정보 1μ°¨ νŒŒμ‹± + β”‚ λ‚ μ§œ, μ‹œκ°„, μž₯μ†Œ λ“± 일정 후보 μΆ”μΆœ + β”‚ + β”œβ”€β”€ Upstage Embedding + Neo4j + β”‚ 의미 맀핑 및 관계·벑터 μΆ”μ²œ 후보 쑰회 β”‚ - β”œβ”€β”€ Neo4j - β”‚ 관계 기반 μΆ”μ²œ 후보 쑰회 + β”œβ”€β”€ Upstage LLM + β”‚ μΆ”μ²œ ν•­λͺ© 선택 및 displayText μ •μ œ β”‚ - └── Upstage LLM - μΆ”μ²œ 후보 μ •μ œ + └── Redis/Valkey + μ΅œμ‹  draftRevision 검증 β”‚ β–Ό Spring Server @@ -121,13 +132,15 @@ Client | Step | Component | Responsibility | | --- | --- | --- | -| 1 | Rule Based Parser | λ‚ μ§œ, μ‹œκ°„, μž₯μ†Œ, 일정 μœ ν˜• 후보 μΆ”μΆœ | -| 2 | Kiwi | ν•œκ΅­μ–΄ ν˜•νƒœμ†Œ 뢄석 보쑰 | -| 3 | Neo4j | 일정과 ν–‰λ™μ˜ 관계 기반 μΆ”μ²œ 후보 쑰회 | -| 4 | Upstage LLM | 쀑볡 후보 톡합 및 λΆˆν•„μš”ν•œ 후보 제거 | -| 5 | Recommender | μ‹œκ°„ν˜•/λΉ„μ‹œκ°„ν˜• λΆ„λ₯˜, μΆ”μ²œ 개수 μ œν•œ, μ΅œμ’… 응닡 ꡬ성 | +| D101 | Schedule Context + Upstage Embedding | 일정 정보λ₯Ό μž„λ² λ”© μž…λ ₯으둜 κ΅¬μ„±ν•˜κ³  쿼리 벑터 생성 | +| D102 | Neo4j | EventType, Context, PlaceType 의미 맀핑 및 관계·벑터 μΆ”μ²œ 후보 κ²°ν•© | +| D103 | Upstage LLM | 후보 쀑 μ΅œλŒ€ 3개λ₯Ό μ„ νƒν•˜κ³  μžμ—°μŠ€λŸ¬μš΄ `displayText`둜 μ •μ œ | +| D104 | Temporal Validator | λ‚ μ§œ λ§₯락 검증 및 `TIMED_ACTION`Β·`UNTIMED_PREP` ν™•μ • | +| D105 | Suggestion Composer | μˆœμœ„μ™€ λΆ€λͺ¨ μž„μ‹œ 일정 IDλ₯Ό κ²€μ¦ν•˜κ³  μ΅œμ’… 응닡 ꡬ성 | -> Upstage LLMμ—λŠ” μΆ”μ²œ μ •μ œμ— ν•„μš”ν•œ μ΅œμ†Œν•œμ˜ 일정 정보와 Neo4j 후보 λͺ©λ‘λ§Œ μ „λ‹¬ν•©λ‹ˆλ‹€. κ°œμΈμ •λ³΄λ‚˜ λ―Όκ°ν•œ 상세 λ©”λͺ¨λŠ” μ „λ‹¬ν•˜μ§€ μ•ŠλŠ” 것을 μ›μΉ™μœΌλ‘œ ν•©λ‹ˆλ‹€. +Spring μ„œλ²„λŠ” `tempEventId`별 μ΅œμ‹  `draftRevision`을 Redis에 λ“±λ‘ν•©λ‹ˆλ‹€. FastAPIλŠ” D101~D105 단계 μ‚¬μ΄μ—μ„œ `recommendation:latest-revision:{tempEventId}`λ₯Ό μ‘°νšŒν•˜κ³ , 였래된 μš”μ²­μ΄λ©΄ `409 STALE_DRAFT_REVISION_409`둜 후속 처리λ₯Ό μ€‘λ‹¨ν•©λ‹ˆλ‹€. Redisλ₯Ό μ‚¬μš©ν•  수 없을 λ•Œμ—λŠ” μΆ”μ²œ νŒŒμ΄ν”„λΌμΈμ„ 계속 μ‹€ν–‰ν•˜λŠ” fail-open 정책을 μ μš©ν•©λ‹ˆλ‹€. + +> Upstageμ—λŠ” 뢄석과 μΆ”μ²œ μ •μ œμ— ν•„μš”ν•œ 일정 정보 및 Neo4j ν›„λ³΄λ§Œ μ „λ‹¬ν•©λ‹ˆλ‹€. κ°œμΈμ •λ³΄λ‚˜ λΆˆν•„μš”ν•œ 민감 μ •λ³΄λŠ” μ „λ‹¬ν•˜μ§€ μ•ŠλŠ” 것을 μ›μΉ™μœΌλ‘œ ν•©λ‹ˆλ‹€. --- @@ -137,36 +150,42 @@ Client brain/ β”œβ”€ app/ β”‚ β”œβ”€ main.py -β”‚ β”œβ”€ config.py -β”‚ β”‚ β”‚ β”œβ”€ api/ β”‚ β”‚ └─ v1/ β”‚ β”‚ β”œβ”€ router.py β”‚ β”‚ └─ routes/ -β”‚ β”‚ └─ health.py -β”‚ β”‚ -β”‚ β”œβ”€ global_response/ -β”‚ β”‚ └─ response.py -β”‚ β”‚ -β”‚ β”œβ”€ global_exception/ +β”‚ β”‚ β”œβ”€ event_previews.py +β”‚ β”‚ β”œβ”€ health.py +β”‚ β”‚ └─ recommendations.py +β”‚ β”œβ”€ core/ +β”‚ β”‚ β”œβ”€ config.py +β”‚ β”‚ β”œβ”€ deps.py β”‚ β”‚ β”œβ”€ error_code.py -β”‚ β”‚ β”œβ”€ exceptions.py -β”‚ β”‚ └─ handlers.py -β”‚ β”‚ +β”‚ β”‚ β”œβ”€ handlers.py +β”‚ β”‚ β”œβ”€ internal_auth.py +β”‚ β”‚ β”œβ”€ responses.py +β”‚ β”‚ └─ valkey_client.py β”‚ β”œβ”€ graph/ -β”‚ β”‚ └─ neo4j_client.py -β”‚ β”‚ -β”‚ β”œβ”€ parser/ -β”‚ β”œβ”€ recommender/ -β”‚ β”œβ”€ llm/ +β”‚ β”‚ β”œβ”€ neo4j_client.py +β”‚ β”‚ β”œβ”€ models/ +β”‚ β”‚ └─ repositories/ β”‚ β”œβ”€ schemas/ +β”‚ β”‚ β”œβ”€ recommendation/ +β”‚ β”‚ β”œβ”€ event_preview.py β”‚ β”‚ └─ health.py β”‚ └─ services/ -β”‚ -β”œβ”€ scripts/ -β”‚ β”œβ”€ sample_data.py -β”‚ └─ test_connection.py -β”‚ +β”‚ β”œβ”€ event_preview_service.py +β”‚ β”œβ”€ parser_service.py +β”‚ └─ recommendation/ +β”‚ β”œβ”€ schedule_context_service.py +β”‚ β”œβ”€ candidate_search_service.py +β”‚ β”œβ”€ refinement_service.py +β”‚ β”œβ”€ temporal_validation_service.py +β”‚ β”œβ”€ suggestion_compose_service.py +β”‚ └─ revision_guard_service.py +β”œβ”€ tests/ +β”œβ”€ nginx/ +β”œβ”€ Dockerfile β”œβ”€ requirements.txt β”œβ”€ .env.example └─ README.md @@ -178,56 +197,73 @@ brain/ | Package | Responsibility | | --- | --- | -| `app.main` | FastAPI μ•± μ§„μž…μ , λΌμš°ν„° 및 μ˜ˆμ™Έ ν•Έλ“€λŸ¬ 등둝 | -| `app.config` | ν™˜κ²½λ³€μˆ˜ 및 μ„€μ • 관리 | -| `app.api` | FastAPI λΌμš°ν„° 및 μ—”λ“œν¬μΈνŠΈ μ •μ˜ | -| `app.global_response` | 곡톡 응닡 객체 관리 | -| `app.global_exception` | 곡톡 μ—λŸ¬ μ½”λ“œ, λΉ„μ¦ˆλ‹ˆμŠ€ μ˜ˆμ™Έ, μ˜ˆμ™Έ ν•Έλ“€λŸ¬ 관리 | -| `app.graph` | Neo4j μ—°κ²° 및 κ·Έλž˜ν”„ 쑰회 둜직 | -| `app.parser` | μžμ—°μ–΄ 일정 1μ°¨ νŒŒμ‹± 둜직 | -| `app.recommender` | μΆ”μ²œ 후보 μ‘°ν•©, μ‹œκ°„ν˜•/λΉ„μ‹œκ°„ν˜• λΆ„λ₯˜, μ΅œμ’… μΆ”μ²œ 생성 | -| `app.llm` | Upstage LLM 연동 둜직 | -| `app.schemas` | μš”μ²­/응닡 DTO μ •μ˜ | -| `app.services` | API 흐름 및 λΉ„μ¦ˆλ‹ˆμŠ€ 둜직 μ‘°ν•© | +| `app.main` | FastAPI μ•± μ§„μž…μ κ³Ό Neo4jΒ·Redis 생λͺ…μ£ΌκΈ° 관리 | +| `app.core` | ν™˜κ²½λ³€μˆ˜, μ˜μ‘΄μ„±, λ‚΄λΆ€ 인증, 곡톡 μ‘λ‹΅Β·μ˜ˆμ™Έ 및 Redis μ—°κ²° 관리 | +| `app.api` | ν—¬μŠ€μ²΄ν¬, 일정 미리보기, μΆ”μ²œ API μ—”λ“œν¬μΈνŠΈ μ •μ˜ | +| `app.graph` | Neo4j μ—°κ²°κ³Ό 일정 의미 λ§€ν•‘Β·μΆ”μ²œ 후보 쑰회 | +| `app.schemas` | νŒŒμ‹±Β·μΆ”μ²œ νŒŒμ΄ν”„λΌμΈμ˜ μš”μ²­/응닡 λͺ¨λΈ μ •μ˜ | +| `app.services` | μžμ—°μ–΄ νŒŒμ‹± 및 D101~D105 μΆ”μ²œ λΉ„μ¦ˆλ‹ˆμŠ€ 둜직 μˆ˜ν–‰ | --- ## πŸš€ μ‹œμž‘ν•˜κΈ° +Python 3.13 ν™˜κ²½μ„ ꢌμž₯ν•©λ‹ˆλ‹€. + ### 1. κ°€μƒν™˜κ²½ 생성 -```powershell -python -m venv .venv +```bash +python3.13 -m venv .venv ``` ### 2. μ˜μ‘΄μ„± μ„€μΉ˜ -```powershell -.\.venv\Scripts\python.exe -m pip install -r requirements.txt +```bash +.venv/bin/python -m pip install -r requirements.txt ``` +Windows PowerShellμ—μ„œλŠ” `.venv/bin/python` λŒ€μ‹  `.\.venv\Scripts\python.exe`λ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€. + ### 3. ν™˜κ²½λ³€μˆ˜ 파일 생성 -```powershell -Copy-Item .env.example .env +```bash +cp .env.example .env ``` +둜컬 Neo4j, Redis/Valkey 및 Upstage API 정보λ₯Ό `.env`에 μ„€μ •ν•©λ‹ˆλ‹€. `VALKEY_HOST`λ₯Ό λΉ„μ›Œλ‘λ©΄ Redis 기반 κΈ°λŠ₯은 λΉ„ν™œμ„±ν™”λ˜λ©° μ„œλ²„λŠ” 계속 μ‹€ν–‰λ©λ‹ˆλ‹€. + ### 4. μ„œλ²„ μ‹€ν–‰ -```powershell -.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 +```bash +.venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 +``` + +ν…ŒμŠ€νŠΈλŠ” λ‹€μŒ λͺ…λ Ήμ–΄λ‘œ μ‹€ν–‰ν•©λ‹ˆλ‹€. + +```bash +PYTHONPATH=. .venv/bin/python -m pytest ``` --- ## πŸ“– API Documentation -FastAPI Brain ServerλŠ” FastAPI κΈ°λ³Έ Swagger UIλ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€. +FastAPI brain μ„œλ²„λŠ” FastAPI κΈ°λ³Έ Swagger UIλ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€. ```text http://127.0.0.1:8000/docs ``` +λΉ„μ¦ˆλ‹ˆμŠ€ APIλŠ” `X-Internal-Api-Key` ν—€λ”λ‘œ Spring μ„œλ²„μ™€μ˜ λ‚΄λΆ€ 톡신을 μΈμ¦ν•©λ‹ˆλ‹€. ν—¬μŠ€μ²΄ν¬λŠ” 인증 λŒ€μƒμ—μ„œ μ œμ™Έλ©λ‹ˆλ‹€. + +| Method | Path | Description | +| --- | --- | --- | +| `GET` | `/api/v1/health` | Neo4j 및 Redis μ—°κ²° μƒνƒœ 확인 | +| `POST` | `/api/v1/event-previews` | μžμ—°μ–΄ 일정 νŒŒμ‹± 및 미리보기 생성 | +| `POST` | `/api/v1/recommendations` | D101~D105 μΆ”μ²œ νŒŒμ΄ν”„λΌμΈ μ‹€ν–‰ | + +μΆ”μ²œ API의 `stop_after_step` μΏΌλ¦¬λŠ” 개발 ν™˜κ²½μ—μ„œ 쀑간 κ²°κ³Όλ₯Ό 확인할 λ•Œλ§Œ μ‚¬μš©ν•  수 있으며 운영 ν™˜κ²½μ—μ„œλŠ” `403`을 λ°˜ν™˜ν•©λ‹ˆλ‹€. + --- ## βœ… Health Check @@ -240,31 +276,28 @@ Response: ```json { - "success": true, - "code": "COMMON_200", - "message": "Tryna Brain server is running.", - "data": { - "status": "ok" + "status": "UP", + "timestamp": "2026-08-13T09:00:00Z", + "components": { + "neo4j": { + "status": "UP", + "detail": null + }, + "redis": { + "status": "UP", + "detail": null + } } } ``` +Redis/Valkeyκ°€ μ„€μ •λ˜μ§€ μ•Šμ€ 둜컬 ν™˜κ²½μ—μ„œλŠ” `components.redis.status`κ°€ `DISABLED`둜 ν‘œμ‹œλ©λ‹ˆλ‹€. ν˜„μž¬ 전체 μƒνƒœμ™€ HTTP μƒνƒœ μ½”λ“œλŠ” Neo4j μ—°κ²° μƒνƒœλ₯Ό κΈ°μ€€μœΌλ‘œ κ²°μ •ν•©λ‹ˆλ‹€. + --- ## πŸ“¦ Common Response -λͺ¨λ“  API 응닡은 곡톡 응닡 객체λ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€. - -Success: - -```json -{ - "success": true, - "code": "COMMON_200", - "message": "μš”μ²­μ΄ μ„±κ³΅ν–ˆμŠ΅λ‹ˆλ‹€.", - "data": {} -} -``` +λΉ„μ¦ˆλ‹ˆμŠ€ μ˜ˆμ™Έμ™€ μš”μ²­κ°’ 검증 였λ₯˜λŠ” 곡톡 응닡 객체λ₯Ό μ‚¬μš©ν•©λ‹ˆλ‹€. Error: @@ -277,36 +310,47 @@ Error: } ``` -응닡 데이터가 μ—†λŠ” 경우 `data`λŠ” `null`둜 λ°˜ν™˜ν•©λ‹ˆλ‹€. +일정 미리보기, μΆ”μ²œ 성곡 응닡 및 ν—¬μŠ€μ²΄ν¬ 응닡은 각 API의 응닡 μŠ€ν‚€λ§ˆλ₯Ό 직접 λ°˜ν™˜ν•©λ‹ˆλ‹€. λ”°λΌμ„œ λͺ¨λ“  성곡 응닡이 `success`, `code`, `message`, `data` ν˜•μ‹μœΌλ‘œ κ°μ‹Έμ§€μ§€λŠ” μ•ŠμŠ΅λ‹ˆλ‹€. --- ## ⚠️ Error Handling -곡톡 μ˜ˆμ™Έ μ²˜λ¦¬λŠ” `app/global_exception`μ—μ„œ κ΄€λ¦¬ν•©λ‹ˆλ‹€. +곡톡 μ˜ˆμ™Έ μ²˜λ¦¬λŠ” `app/core`μ—μ„œ κ΄€λ¦¬ν•©λ‹ˆλ‹€. -ν˜„μž¬ κΈ°λ³Έ μ—λŸ¬ μ½”λ“œλŠ” λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€. +ν˜„μž¬ μ£Όμš” μ—λŸ¬ μ½”λ“œλŠ” λ‹€μŒκ³Ό κ°™μŠ΅λ‹ˆλ‹€. -| Code | Description | -| --- | --- | -| `COMMON_400` | 잘λͺ»λœ μš”μ²­ | -| `COMMON_404` | λ¦¬μ†ŒμŠ€ μ—†μŒ | -| `COMMON_422` | μš”μ²­κ°’ 검증 μ‹€νŒ¨ | -| `COMMON_500` | μ„œλ²„ λ‚΄λΆ€ 였λ₯˜ | -| `NEO4J_503` | Neo4j μ—°κ²° μ‚¬μš© λΆˆκ°€ | - -μΆ”ν›„ parser, graph, llm, recommender κΈ°λŠ₯이 μΆ”κ°€λ˜λ©΄ 도메인별 μ—λŸ¬ μ½”λ“œλ₯Ό ν™•μž₯ν•©λ‹ˆλ‹€. +| Code | HTTP Status | Description | +| --- | --- | --- | +| `COMMON_400` | 400 | 잘λͺ»λœ μš”μ²­ | +| `INTERNAL_AUTH_401` | 401 | μ„œλ²„ κ°„ 인증 μ‹€νŒ¨ | +| `COMMON_403` | 403 | ν˜„μž¬ ν™˜κ²½μ—μ„œ μ‚¬μš©ν•  수 μ—†λŠ” κΈ°λŠ₯ | +| `COMMON_404` | 404 | λ¦¬μ†ŒμŠ€ μ—†μŒ | +| `STALE_DRAFT_REVISION_409` | 409 | μ΅œμ‹  μž…λ ₯이 μ‘΄μž¬ν•˜λŠ” 이전 μΆ”μ²œ μš”μ²­ 쀑단 | +| `COMMON_422` | 422 | μš”μ²­κ°’ 검증 μ‹€νŒ¨ | +| `COMMON_500` | 500 | μ„œλ²„ λ‚΄λΆ€ 였λ₯˜ | +| `INTERNAL_AUTH_500` | 500 | λ‚΄λΆ€ API 인증 μ„€μ • λˆ„λ½ | +| `EMBEDDING_400` | 400 | μž„λ² λ”© μž…λ ₯κ°’ λˆ„λ½ | +| `EMBEDDING_503` | 503 | μž„λ² λ”© λͺ¨λΈ 연동 λΆˆκ°€ | +| `NEO4J_503` | 503 | Neo4j μ—°κ²° λΆˆκ°€ | +| `LLM_503` | 503 | LLM 연동 λΆˆκ°€ | --- ## βš™οΈ Environment Configuration -Brain ServerλŠ” `.env` 기반으둜 ν™˜κ²½λ³€μˆ˜λ₯Ό κ΄€λ¦¬ν•©λ‹ˆλ‹€. +brain μ„œλ²„λŠ” `.env` 기반으둜 ν™˜κ²½λ³€μˆ˜λ₯Ό κ΄€λ¦¬ν•©λ‹ˆλ‹€. ```env -APP_NAME=Tryna Brain +APP_NAME=tryna brain APP_ENV=local API_V1_PREFIX=/api/v1 +ROOT_PATH= +INTERNAL_API_KEY=local-internal-api-key + +VALKEY_HOST=localhost +VALKEY_PORT=6379 +VALKEY_PASSWORD= NEO4J_URI=neo4j://localhost:7687 NEO4J_USERNAME=neo4j @@ -314,9 +358,21 @@ NEO4J_PASSWORD=password NEO4J_DATABASE=neo4j UPSTAGE_API_KEY= +UPSTAGE_API_KEY_MULTI= +UPSTAGE_QUERY_EMBEDDING_MODEL=solar-embedding-1-large-query +UPSTAGE_PASSAGE_EMBEDDING_MODEL=solar-embedding-1-large-passage +UPSTAGE_EMBEDDING_TIMEOUT_SECONDS=10 +UPSTAGE_CHAT_MODEL=solar-pro3 +UPSTAGE_CHAT_TIMEOUT_SECONDS=20 + +D102_EMBEDDING_DIMENSION=4096 +D102_EVENT_TYPE_MIN_SCORE=0.61 +D102_CONTEXT_MIN_SCORE=0.63 +D102_PLACE_TYPE_MIN_SCORE=0.63 +D102_RECOMMENDATION_MIN_SCORE=0.62 ``` -`.env`λŠ” Git에 μ»€λ°‹ν•˜μ§€ μ•Šκ³ , `.env.example`만 κ³΅μœ ν•©λ‹ˆλ‹€. +운영 ν™˜κ²½(`APP_ENV=prod`)μ—μ„œλŠ” Redis/Valkey 연결에 TLS와 μ‹œμŠ€ν…œ CA μΈμ¦μ„œ 검증을 μ μš©ν•©λ‹ˆλ‹€. `.env`λŠ” Git에 μ»€λ°‹ν•˜μ§€ μ•Šκ³  `.env.example`만 κ³΅μœ ν•©λ‹ˆλ‹€. --- @@ -324,6 +380,14 @@ UPSTAGE_API_KEY= 민감 μ •λ³΄λŠ” μ €μž₯μ†Œμ— μ»€λ°‹ν•˜μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. +λ‹€μŒ 값은 둜컬 `.env` λ˜λŠ” 배포 ν™˜κ²½μ˜ secret으둜 κ΄€λ¦¬ν•©λ‹ˆλ‹€. + +- `INTERNAL_API_KEY` +- `NEO4J_PASSWORD` +- `VALKEY_PASSWORD` +- `UPSTAGE_API_KEY` +- `UPSTAGE_API_KEY_MULTI` + `.gitignore`에 λ‹€μŒ 파일과 디렉터리λ₯Ό μ œμ™Έν•˜λ„λ‘ μ„€μ •ν•©λ‹ˆλ‹€. ```gitignore @@ -338,29 +402,26 @@ __pycache__/ ## βœ… Current Setup Checklist -- [x] ν•„μš”ν•œ μ˜μ‘΄μ„± μΆ”κ°€ -- [x] 민감 정보 μ œμ™Έλ₯Ό μœ„ν•œ `.gitignore` μ„€μ • -- [x] FastAPI Swagger UI 확인 κ°€λŠ₯ -- [x] 곡톡 응닡 객체 μ„ΈνŒ… -- [x] 곡톡 μ—λŸ¬ ν•Έλ“€λŸ¬ μ„ΈνŒ… -- [x] Health Check API μ„ΈνŒ… -- [x] 둜컬 μ„œλ²„ μ‹€ν–‰ 확인 +- [x] μžμ—°μ–΄ 일정 미리보기 API κ΅¬ν˜„ +- [x] D101~D105 μΆ”μ²œ νŒŒμ΄ν”„λΌμΈ κ΅¬ν˜„ +- [x] Neo4j μ—°κ²° 및 관계·벑터 μΆ”μ²œ 후보 쑰회 +- [x] Upstage μž„λ² λ”© 및 μΆ”μ²œ 문ꡬ μ •μ œ +- [x] Redis/Valkey μ—°κ²° 및 μ΅œμ‹  revision 검증 +- [x] λ‚΄λΆ€ API ν‚€ 인증 +- [x] 곡톡 μ˜ˆμ™Έ μ²˜λ¦¬μ™€ Health Check API +- [x] Docker 및 GitHub Actions CI/CD ꡬ성 +- [x] pytest ν…ŒμŠ€νŠΈ ꡬ성 --- ## πŸ—Ί 개발 λ‘œλ“œλ§΅ -- [x] Python ν™˜κ²½ ꡬ좕 -- [x] FastAPI μ„œλ²„ 초기 μ„ΈνŒ… -- [x] Health Check API ꡬ좕 -- [x] 곡톡 응닡 객체 ꡬ좕 -- [x] 곡톡 μ—λŸ¬ ν•Έλ“€λŸ¬ ꡬ좕 -- [x] Neo4j client κΈ°λ³Έ ꡬ쑰 정리 -- [ ] μžμ—°μ–΄ 일정 1μ°¨ νŒŒμ‹± API κ΅¬ν˜„ -- [ ] Kiwi ν˜•νƒœμ†Œ 뢄석 연동 -- [ ] Neo4j μ‹€μ œ μ—°κ²° ν™˜κ²½ ꡬ성 -- [ ] Neo4j μ§€μ‹λ² μ΄μŠ€ ꡬ좕 -- [ ] Neo4j μΆ”μ²œ 후보 쑰회 κ΅¬ν˜„ -- [ ] Upstage LLM 연동 -- [ ] μΆ”μ²œ ν•­λͺ© 생성 둜직 κ΅¬ν˜„ -- [ ] Spring Server 연동 \ No newline at end of file +- [x] Python 및 FastAPI μ‹€ν–‰ ν™˜κ²½ ꡬ좕 +- [x] μžμ—°μ–΄ 일정 1μ°¨ νŒŒμ‹±κ³Ό Kiwi 연동 +- [x] Neo4j μ—°κ²° 및 μ§€μ‹λ² μ΄μŠ€ ꡬ좕 +- [x] Neo4j 의미 맀핑과 μΆ”μ²œ 후보 쑰회 κ΅¬ν˜„ +- [x] 관계·벑터 μΆ”μ²œ 후보 κ²°ν•© +- [x] Upstage μž„λ² λ”© 및 LLM 연동 +- [x] μΆ”μ²œ ν•­λͺ© μ‹œκ°„ λ§₯락 검증과 μ΅œμ’… 응닡 ꡬ성 +- [x] Redis 기반 였래된 μΆ”μ²œ μš”μ²­ 후속 처리 차단 +- [x] Spring μ„œλ²„ λ‚΄λΆ€ API 연동