ScopeKit: 복잡한 고객 요구사항을 로컬 Gemma를 이용해 견적서로 변환하기

이 글은 Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle에 제출하는 내용입니다.

제가 만든 것 (What I Built)

“간단한 웹사이트만 만들면 돼요”라는 말 뒤에는 놀라울 정도로 긴 대화가 숨어 있을 수 있습니다. 어떤 페이지가 필요한지? 사진은 누가 제공하는지? “문의 양식”에 이메일 전송 기능이 포함되는지? 결제 과정도 이 단계에 포함되는지?

저는 프리랜서들이 이러한 비공식적인 메시지를 검토하고 견적을 낼 수 있는 형태로 변환할 수 있도록 작은 로컬 AI 작업 공간인 ScopeKit을 만들었습니다.

고객의 요구사항(brief)을 붙여넣으면 Gemma가 범위를 제안하고, 결과물과 시간을 검토하며, 적정 요율을 설정한 다음, 고객에게 회신하는 마크다운 형식의 제안서를 내보낼 수 있습니다. 원문 구절은 제안된 작업 옆에 배치되어 있어 요청 사항으로 추적할 수 있습니다.

이 도구의 목표 사용자는 독립 웹 디자이너 또는 소규모 프리랜서 스튜디오입니다. 잠재적인 유료 서비스로는 브랜드화된 제안 워크플로우 설치 및 맞춤 설정이 있습니다. 하지만 이 사업 아이디어는 아직 가설 단계에 머물러 있으며, 지불 의사나 실제 고객 확보, 매출은 테스트하지 않았습니다.

프로젝트는 의도적으로 작게 설계되었습니다. 계정 시스템이나 고객 데이터베이스는 없습니다. 작업 내용은 메모리에 유지되며, 외관 설정(appearance preference)만 브라우저에 저장됩니다.

데모 (Demo)

28초 ScopeKit 사용 방법 영상 시청하기 (MP4)

이 영상은 가상의 꽃집 요구사항(florist brief)과 실제 로컬 Gemma 추론을 사용한 편집된 UI 단계 시퀀스입니다. 영상 속 일시 정지 시간은 추론 시간이 아님을 유의하세요.

테스트 요구사항은 1페이지 분량의 꽃집 웹사이트, 웨딩 부케 갤러리, 문의 양식, 그리고 전화기 호환성을 요청합니다. Gemma는 웹사이트, 갤러리, 문의 양식을 식별한 다음, 질문, 가정 사항, 제외 항목을 제안합니다.

또한 총 2시간의 작업만 필요하다고 제안합니다. 이것이 검토(review)가 워크플로우에 포함된 이유입니다. 시연에서는 시간을 수동으로 5시간, 3시간, 그리고 3시간으로 변경했습니다. 시간당 $50와 15%의 비상 예비비를 적용하면, 예시 견적은 $632.50가 되고, 보증금(deposit)은 $316.25입니다. 이 수치들은 검증된 노력 예측이 아닌, 참고용 계획 수치입니다.

모델은 또한 제안된 제외 항목에 “기본 휴대폰 호환성을 넘어서는 모바일 반응성”을 포함하고 있습니다. 고객은 명시적으로 휴대폰 지원을 요청했으므로, 이 문구는 공유하기 전에 명확히 해야 합니다. 이 도구는 특정 범위(scope)가 완성되었는지 또는 제안된 조건이 적절한지 판단하지 않습니다.

로컬에서 사용해 보기:

git clone https://github.com/Kushaal-k/ScopeKit.git
cd ScopeKit
ollama pull gemma3:1b
...

먼저 Ollama와 Python 3.10 이상을 설치하세요. Ollama를 실행 상태로 유지한 후, http://127.0.0.1:8765를 여세요. Windows 사용자는 start.cmd를 사용할 수 있습니다. 손으로 작성된 예시 실행(Try an example) 옵션은 모델 없이 편집 및 내보내기 기능을 탐색할 수 있게 해주며, 이는 샘플로 명확하게 표시되어 있습니다.

코드

GitHub의 ScopeKit

MIT 라이선스가 적용된 이 저장소에는 설정 지침, 19개의 자동화 테스트, 크로스 플랫폼 CI 워크플로우, 데모 비디오, 실제 모델 응답, 그리고 검토된 제안서 내보내기 기능이 포함되어 있습니다.

제작 과정

프론트엔드는 순수 HTML, CSS, JavaScript로 구성되었습니다. Python 표준 라이브러리 서버가 유효성 검사(validation), 견적 산출(quoting), 그리고 로컬 Ollama 연결을 처리합니다. 파이썬 애플리케이션 종속성이나 프론트엔드 빌드 도구는 없습니다.

Gemma 3 1B는 Ollama의 스키마 제약 채팅 API를 통해 핵심 추출 작업을 수행합니다. 지침과 간략한 사용법은 Gemma의 프롬프트 구조와 일관되게 사용자 턴(user turn)을 사용합니다.

가장 유용한 교훈은 출처 증거에서 나왔습니다. 초기 접근 방식에서는 모델에게 근거가 되는 인용구를 생성하도록 요청했습니다. 이 경우 때때로 존재하지 않는 내용을 지어내기도 했습니다. 사용 가능한 인용구에 제약을 가했음에도 불구하고, 여전히 관련 없는 구절을 선택할 수 있었습니다.

최종 접근 방식은 이 기계적인 단계를 코드로 구현합니다: Gemma가 작업을 제안하면 서버가 작업-단어 중첩(task-word overlap)과 전화/모바일 같은 몇 가지 별칭을 사용하여 정확한 구절들을 연결합니다. 이는 일치하지 않는 작업 이름이나 중복된 작업 앵커를 거부합니다. 오류가 발생하기 전에 한 번의 수정 시도가 허용됩니다.

이것은 추적성 휴리스틱(traceability heuristic)입니다. 이로써 의미론적 정확성, 완전성 또는 중복 작업 부재 여부를 증명할 수는 없습니다.

분리는 돈으로 이어집니다: Python의 Decimal 산술이 인용구를 계산합니다. 모델이 시간을 제안하면 사용자가 이를 검토합니다. 수동으로 편집된 답변은 가격 변경에도 살아남으며, 숫자 확인을 상기시키는 알림이 제공됩니다.

Client brief → local Gemma → validation and source linking
→ human review → decimal quote → Markdown proposal

인터페이스는 Light, Dark, System 테마를 가지고 있으며, 드롭다운 메뉴와 키보드 탐색, 반응형 레이아웃을 지원합니다. 브리프(Briefs)와 제안서(proposals)는 페이지가 다시 로드될 때 지워집니다.

모든 19개의 로컬 검증 및 HTTP 통합 테스트를 통과했습니다. 어댑터 테스트에는 목업 Ollama 서버를 사용하며, 별도의 실제 Gemma 실행은 실제 추론을 검증합니다. GitHub Actions도 통과하여 Windows와 Linux에서 Python 검사를 수행하고 JavaScript 구문 유효성 검사를 진행했습니다.

Open Innovation은 왜 중요한가?

로컬 오픈 가중치 추론(local open-weight inference)은 이 도구가 처리하는 자료, 즉 고객 메시지, 프로젝트 세부 정보 및 초안 상업 약관에 적합합니다.

모델이 다운로드되면 ScopeKit의 추론 워크플로우는 오프라인으로 작동할 수 있습니다. 호스팅된 추론 계정, API 키 또는 요청당 결제가 필요하지 않습니다. 하드웨어와 전기는 여전히 비용이 들고, 작은 모델이라도 실수를 할 수 있습니다.

오픈 웨이트(Open weights) 덕분에 사용자는 애플리케이션과 독립적으로 다른 로컬 모델을 선택할 수 있습니다. 이 모델은 유효성 검사, 계산 및 내보내기 형식이 검사 가능한 워크플로우의 교체 가능한 부분입니다.

이 애플리케이션은 MIT 라이선스를 사용합니다. Gemma 가중치(weights)는 자체 Google Gemma 약관을 가지며, 별도의 다운로드 항목이며 소스 코드에 번들되지 않습니다.

수상 부문 (Prize Categories)

• Gemma 활용 최우수: Gemma 3 1B를 Ollama를 통해 로컬에서 실행하여 제품의 핵심에 있는 작업(tasks), 질문(questions), 가정(assumptions) 및 제외 사항(exclusions)을 추출합니다. 이 저장소에는 실제 추론 증거와 위의 워크스루가 포함되어 있습니다.
• GitHub Copilot 활용 최우수 — GitHub Actions 자동화: 이 챌린지는 명시적으로 GitHub Actions를 이 부문에 포함하고 있습니다. ScopeKit은 Windows/Linux 테스트 매트릭스와 JavaScript 검사에 Actions를 사용하며, 성공적인 실행 기록이 있습니다. 이 항목은 Actions 자동화를 기반으로 하며, 앱은 Codex의 도움을 받아 구축되었습니다.

커뮤니티 연구 (Community research)

AI Explore의 “구조화된 출력은 구문(Syntax)을 제공하지만 의미론(Semantics)을 제공하지는 않는다” 글은 파싱 가능한 출력과 신뢰할 수 있는 제안 사이의 구분을 알려주었습니다. ScopeKit이 고안한 인용문 실패 사례는 그 구분을 구체화했습니다.