Luna: Voice-Enabled Expense Management Agent

Luna: 音声対応の経費管理エージェント

Luna は Langgraph で構築された音声対応の AI アシスタントで、ユーザーが自然な会話を通じて経費を管理するのを支援します。このプロジェクトは、音声テキスト変換とテキスト音声変換機能を強力なエージェントフレームワークと組み合わせた、任意の Langgraph エージェント向けの音声インターフェースを作成する方法を示しています。

🌟 Features

• Voice Interaction: Luna に話しかけると、高品質なテキスト音声変換を通じて応答を聞くことができます
• Expense Management: 自然な会話を通じて経費を作成、照会、更新、削除できます
• Category Classification: 説明に基づいて経費を自動的に分類します
• Database Integration: (Supabase 経由の) PostgreSQL データベースに経費データを保存します
• Tool-using Agent: 複雑な推論のために Langgraph のエージェントフレームワークで構築されています

🛠️ Technology Stack

Backend

• Python 3.13: バックエンドのコア言語
• Langgraph: 会話型 AI を構築するためのエージェントフレームワーク
• OpenAI:
  • 音声テキスト変換用 Whisper API
  • エージェントの推論用 GPT-4 Mini
  • テキスト音声変換応答用 TTS API
• MCP (Model Calling Protocol): ツールの定義と使用のため
• SQLAlchemy: データベースインタラクション用 ORM
• Supabase: PostgreSQL データベースプロバイダー

Audio Processing

• sounddevice: マイクからのオーディオキャプチャ用
• scipy: オーディオファイル処理用

📋 Prerequisites

• Python 3.13
• OpenAI API キー
• Supabase アカウントとデータベース
• マイクとスピーカー

🚀 Getting Started

1. Clone the repository

git clone https://github.com/rosiefaulkner/langgraph-voice-agent.git
cd langgraph-voice-agent

2. Set up a virtual environment and install dependencies

(推奨) 依存関係管理には uv を使用してください

プロジェクトディレクトリに venv をセットアップし、1 つのコマンドですべての依存関係をインストールします。

uv sync

3. Set up environment variables

ルートディレクトリに以下の変数を含む .env ファイルを作成してください:

OPENAI_API_KEY=your_openai_api_key
SUPABASE_URI=postgresql://postgres:[email protected]:5432/postgres

4. Run the application

python main.py

🎤 Using Luna

1. アプリケーションを実行します
2. プロンプトが表示されたら、リクエストを話してください (例: "Create a new expense for lunch today that cost $15")
3. Enter キーを押して録音を停止します
4. Luna がリクエストを処理し、必要に応じてデータベースと対話して、音声で応答します
5. 会話を続けるか、"exit" または "quit" と言ってセッションを終了します

🧩 Project Structure

langgraph-voice-agent/
├── main.py                  # Main application entry point
├── assistant_graph.py       # Langgraph agent definition
├── state.py                 # State management for the agent
├── voice_utils.py           # Audio recording and playback utilities
├── mcps/                    # Model Calling Protocol servers
│   ├── mcp_config.json      # MCP server configuration
│   └── local_servers/
│       └── db.py            # Database tools implementation
├── .env                     # Environment variables (not in repo)
├── .env.example             # Example environment variables
└── pyproject.toml           # Project dependencies

🔧 Customizing the Agent

Modifying the System Prompt

Luna の個性や機能を変更するには、assistant_graph.py の system_prompt を編集してください:

system_prompt = """You are Luna, the company's expense manager...

Adding New Tools

1. mcps/local_servers/ の既存のツールに新しい MCP サーバーを作成するか、ツールを追加します
2. mcps/mcp_config.json でサーバーを登録します
3. ツールはエージェントで自動的に利用可能になります

Changing Voice Settings

voice_utils.py の TTS 設定を変更してください:

async def play_audio(message: str):
    # ...
    async with openai_async.audio.speech.with_streaming_response.create(
        model="gpt-4o-mini-tts",
        voice="fable",  # Change the voice here
        input=cleaned_message,
        instructions="Speak in a cheerful, helpful tone with a brisk pace.",  # Modify instructions
        response_format="pcm",
        speed=1.2,  # Adjust speed
    ) as response:
        # ...

📚 Resources

• Langgraph Documentation
• OpenAI API Documentation
• Model Context Protocol (MCP)
• SQLAlchemy Documentation

🤝 Contributing

貢献を歓迎します! お気軽にプルリクエストを送信してください。