pet-health-agent

소형 반려동물 영양사는 반려동물 보호자를 위한 AI 식이 평가 시스템으로, 핵심 설계는 Agent와 Engine의 엄격한 계층 분리입니다. LangGraph ReAct Agent는 이해, 추가 질문, 스케줄링, 설명을 담당하고, 순수 Python 영양 엔진은 RER/MER, 수정 Atwater, AAFCO 조회표, Ca:P, 질병 제약, 알레르겐 충돌 등의 계산을 수행하며, 모든 데이터에는 source/version/review_date 출처가 포함됩니다. 시스템은 USDA 조회표, 에너지 요구량 계산, 종합 영양 평가, Qwen3-VL 상품 사료 포장 OCR 인식, 반려동물 프로필 관리, 장기 기억 쓰기를 포함한 8개의 단일 책임 도구를 제공합니다. 기억 시스템은 세 계층으로 나뉩니다. MySQL은 스레드 간 프로필과 사실을 영속화하고, SQLite checkpoint는 단일 스레드 AgentState를 저장하며, 메시지가 30개를 초과하면 LLM 요약 압축을 수행합니다. 백엔드는 FastAPI와 SQLAlchemy 비동기 아키텍처를 사용하고, 프론트엔드는 Vue 3 + Pinia + Vite로 구성되며, SSE 스트리밍을 통해 사고, 도구 호출, 평가 보고서를 반환합니다. 시스템은 JWT 인증과 데이터 격리를 강제하며 익명 접근 경로가 없습니다. 프로젝트에는 엔진 단위 테스트, 도구 시그니처, graph smoke 테스트를 포함한 119개의 테스트 케이스가 있습니다. 이 프로젝트는 설명 가능하고 추적 가능한 수직 도메인 Agent가 필요한 개발자에게 참고 자료가 되며, LLM이 수치 계산에 참여하지 않고 도구 매개변수가 RunnableConfig를 통해 주입되어 신원 위조를 방지하는 등의 엔지니어링 실천을 보여줍니다.