daveebbelaar/ai-cookbook

⭐ 2,636 🍴 872 Python📄 MIT License GitHubで見る →

主な特徴

**7つの基本ビルディングブロック**：インテリジェンス、メモリ、ツール、バリデーション、コントロール、リカバリ、フィードバック
**実践的なコード例**：コピー&ペーストで簡単に統合できるコードスニペット
**MCP（Model Context Protocol）クラッシュコース**：7章にわたる完全なチュートリアル
**Mem0を使った長期記憶システム**：持続的で構造化されたメモリの実装
**OpenAI APIの詳細なチュートリアル**：ストリーミング、構造化出力、エージェント等
**ワークフローパターン**：プロンプトチェーン、ルーティング、並列化、オーケストレーター
**実プロダクションの経験に基づくアプローチ**

リポジトリ解析: daveebbelaar/ai-cookbook

基本情報

リポジトリ名: daveebbelaar/ai-cookbook
主要言語: Python
スター数: 2,636
フォーク数: 872
最終更新: 2024年（GitHub Trendingへの掲載時点）
ライセンス: MIT License
トピックス: AIシステム開発、エージェント、MCP、メモリシステム、ワークフロー

概要

一言で言うと

実用的なAIシステムを構築するためのコピー&ペースト可能なコード例とチュートリアルを提供する実践的なCookbook。

詳細説明

ai-cookbookは、AIエンジニアでDataluminaの創設者であるDave Ebbelaar氏が作成した、実践的なAIシステム開発のためのリソース集である。このリポジトリは、「フレームワークはプロダクションで使われていない」という観察に基づき、カスタムビルディングブロックを使用した実用的なアプローチを提唱している。その中心となる哲学は、LLMを戦略的に使用し、決定論的なコードで解決できない場合のみにLLMを呼び出すというものである。

主な特徴

7つの基本ビルディングブロック：インテリジェンス、メモリ、ツール、バリデーション、コントロール、リカバリ、フィードバック
実践的なコード例：コピー&ペーストで簡単に統合できるコードスニペット
MCP（Model Context Protocol）クラッシュコース：7章にわたる完全なチュートリアル
Mem0を使った長期記憶システム：持続的で構造化されたメモリの実装
OpenAI APIの詳細なチュートリアル：ストリーミング、構造化出力、エージェント等
ワークフローパターン：プロンプトチェーン、ルーティング、並列化、オーケストレーター
実プロダクションの経験に基づくアプローチ

使用方法

インストール

前提条件

Python 3.11以上
uv（推奨）またはpip
Docker（一部サンプル用）
OpenAI APIキー（モデルの使用に必要）

インストール手順

# リポジトリのクローン
git clone https://github.com/daveebbelaar/ai-cookbook.git
cd ai-cookbook

# 仮想環境の作成
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 各サブディレクトリの依存関係をインストール
# uvを使用（推奨）
uv pip install -r agents/building-blocks/requirements.txt

# またはpipを使用
pip install -r agents/building-blocks/requirements.txt

基本的な使い方

Hello World相当の例：シンプルなLLM呼び出し（Intelligenceブロック）

# agents/building-blocks/1-intelligence.py
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

print(response.choices[0].message.content)

実践的な使用例：メモリ付きチャットボット

# agents/building-blocks/2-memory.py
conversation_history = []

def chat_with_memory(user_input):
    # 新しいメッセージを履歴に追加
    conversation_history.append({"role": "user", "content": user_input})
    
    # 履歴全体をLLMに送信
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."}
        ] + conversation_history
    )
    
    # アシスタントの応答を履歴に追加
    assistant_message = response.choices[0].message.content
    conversation_history.append({"role": "assistant", "content": assistant_message})
    
    return assistant_message

高度な使い方：MCPサーバーの実装

# mcp/crash-course/3-simple-server-setup/server.py
from mcp.server import Server
import mcp.types as types

# サーバーインスタンスを作成
app = Server("example-server")

# ツールの定義
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="add",
            description="Add two numbers",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

# ツールの実行
@app.call_tool()
async def call_tool(name: str, arguments: any) -> str:
    if name == "add":
        return str(arguments["a"] + arguments["b"])
    return "Unknown tool"

ドキュメント・リソース

公式ドキュメント

README.md: プロジェクトの概要とDave Ebbelaar氏の紹介
agents/building-blocks/README.md: 7つの基本ビルディングブロックの詳細説明
mcp/crash-course/README.md: MCPクラッシュコースの概要
knowledge/mem0/README.md: Mem0を使った長期記憶システムの説明

サンプル・デモ

agents/building-blocks/*.py: 7つのビルディングブロックの実装例
mcp/crash-course/: MCPのサーバー/クライアント実装例
knowledge/mem0/oss/: Mem0オープンソース版の実装例
models/openai/: OpenAI APIの様々な使用例
patterns/workflows/: ワークフローパターンの実装

チュートリアル・ガイド

YouTubeチャンネル: https://www.youtube.com/@daveebbelaar
Data Alchemyコミュニティ: https://www.skool.com/data-alchemy
GenAI Launchpad: https://launchpad.datalumina.com/
MCP公式ドキュメント: https://modelcontextprotocol.io
Mem0公式ドキュメント: https://docs.mem0.ai/

技術的詳細

アーキテクチャ

全体構造

ai-cookbookは、実践的なアプローチに基づくモジュラーな構造を採用している。各ディレクトリは特定の概念やツールに焦点を当て、独立した学習ユニットとして機能する。これにより、開発者は必要な部分だけを選択して学習・利用できる。

ディレクトリ構成

ai-cookbook/
├── agents/              # AIエージェント構築の基礎
│   └── building-blocks/ # 7つの基本ビルディングブロック
├── knowledge/           # 知識管理・メモリシステム
│   ├── docling/         # ドキュメント処理・チャンキング
│   └── mem0/            # 長期記憶システム
├── mcp/                 # Model Context Protocol
│   └── crash-course/    # MCPクラッシュコース（7章）
├── models/              # LLMモデルの使用例
│   └── openai/          # OpenAI APIの詳細例
└── patterns/            # デザインパターン
    └── workflows/       # ワークフローパターン

主要コンポーネント

7つのビルディングブロック: AIエージェント構築の基礎要素
- 場所: agents/building-blocks/
- 依存: OpenAI API、基本Pythonライブラリ
- インターフェース: 各ブロックは独立したモジュールとして実装
MCPサーバー/クライアント: 標準化されたモデルコンテキストプロトコル
- 場所: mcp/crash-course/
- 依存: mcpライブラリ、asyncio
- インターフェース: stdio、SSE、HTTPサポート
Mem0メモリシステム: 持続的なコンテキスト管理
- 場所: knowledge/mem0/
- 依存: Qdrant、Neo4j（オプション）、OpenAI
- インターフェース: add()、search()、get_all()、update()

技術スタック

コア技術

言語: Python 3.11+
フレームワーク:
- フレームワークを意図的に使用せず、カスタムビルディングブロックを推奨
- 決定論的なコードと戦略的なLLM呼び出しの組み合わせ
主要ライブラリ:
- openai: OpenAI APIクライアント
- mcp: Model Context Protocol SDK
- mem0: 長期記憶システム
- instructor: 構造化出力の検証
- pydantic: データバリデーション
- asyncio: 非同期処理
- qdrant-client: ベクトルデータベース

開発・運用ツール

ビルドツール:
- uv（推奨）: 高速Pythonパッケージマネージャ
- venv: Python仮想環境
- Docker: Mem0 OSS版の依存サービス
テスト:
- サンプルコードによる実践的な検証
- MCP Inspectorによるサーバーテスト
CI/CD:
- GitHubリポジトリでのコード管理
- コミュニティベースの貢献
デプロイ:
- Claude DesktopへのMCPサーバーインストール
- Docker Composeによるローカル環境構築

設計パターン・手法

決定論的コード優先: LLMを「最後の手段」として使用
コンテキストエンジニアリング: 適切なコンテキストを適切なタイミングで提供
DAG（有向非巡回グラフ）ベースのワークフロー: 明確な処理フロー
モジュラー設計: 各ビルディングブロックの独立性
エラーハンドリングファースト: リカバリメカニズムの重要性
人間のループ内処理: 重要な意思決定には承認フロー

データフロー・処理フロー

入力受付: ユーザー入力またはシステムイベント
コントロールフロー: 決定論的なルーティングと分岐
LLM呼び出し（必要時）:
- コンテキストの準備（メモリからの取得）
- プロンプトの構築
- API呼び出し
バリデーション: 出力の検証と再試行
ツール実行（必要時）: 外部APIやシステム操作
フィードバックループ: 人間の承認または修正
結果の保存: メモリへの記録、ログ出力

API・インターフェース

公開API

MCPサーバーAPI

目的: ツール、リソース、プロンプトの提供
使用例:

# ツールの定義
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [types.Tool(name="add", description="Add two numbers")]

# プロンプトの定義
@app.list_prompts()
async def list_prompts() -> list[types.Prompt]:
    return [types.Prompt(name="summarize", description="Summarize content")]

Mem0 Memory API

目的: 持続的なメモリ管理
使用例:

# メモリの追加
memory.add(messages=[{"role": "user", "content": "I love pizza"}], user_id="user123")

# メモリの検索
results = memory.search("food preferences", user_id="user123")

設定・カスタマイズ

設定ファイル

# Mem0設定例
config = {
    "vector_store": {
        "provider": "qdrant",
        "config": {"host": "localhost", "port": 6333}
    },
    "llm": {
        "provider": "openai",
        "config": {"model": "gpt-4"}
    },
    "custom_fact_extraction_prompt": "Extract key facts..."
}

拡張・プラグイン開発

カスタムビルディングブロック: 7つの基本要素を組み合わせて新しい機能を構築
MCPサーバープラグイン: 新しいツールやリソースを追加
ワークフローパターン: プロンプトチェーン、ルーティング、リフレクションの組み合わせ

パフォーマンス・スケーラビリティ

パフォーマンス特性

Mem0の性能:
- OpenAI Memoryより26%高い精度
- フルコンテキストアプローチより91%低いレイテンシ
- 90%のトークン節約
最適化手法:
- LLM呼び出しの最小化
- 決定論的コードの最大活用
- ベクトル検索による効率的なメモリ取得

スケーラビリティ

モジュラー設計: 必要なビルディングブロックのみを使用
非同期処理: MCPサーバーによる効率的な通信
ベクトルデータベース: Qdrantによる高速検索
Docker化: 環境依存の最小化

制限事項

技術的な制限:
- OpenAI APIのレート制限
- コンテキストウィンドウのサイズ制約
- ローカルモデル対応は一部のみ
運用上の制限:
- APIキーの管理が必要
- コスト管理（LLM API呼び出し）
- フレームワーク非使用のため、初心者には学習曲線がある

評価・所感

技術的評価

強み

実践的で現実的なアプローチ
コピー&ペースト可能な実動コード
包括的な学習リソース（MCP、Mem0、OpenAI API等）
プロダクション経験に基づくベストプラクティス
モジュラーな設計で必要な部分だけ学習可能
フレームワークに依存しない柔軟性

改善の余地

テストコードの不足
エラーハンドリングの詳細な実装例が限定的
CI/CDパイプラインの例がない
日本語ドキュメントの不足

向いている用途

AIシステム開発の学習・プロトタイピング
カスタムAIエージェントの構築
既存システムへのAI機能の統合
チャットボットやアシスタントの開発
バックグラウンド自動化システム

向いていない用途

大規模エンタープライズシステム（そのままの使用）
フレームワークに依存した開発を好むチーム
コードを書かずにAIシステムを構築したい場合
セキュリティが最優先のシステム

総評

ai-cookbookは、AIシステム開発の現実的なアプローチを示す優れたリソースである。「フレームワークはプロダクションで使われていない」という大胆な主張は、実際の経験に裏打ちされており、特にバックグラウンド自動化システムを構築する開発者にとって価値が高い。

7つのビルディングブロックというシンプルなアプローチは、複雑なAIシステムを理解しやすくし、必要な機能を段階的に実装できるようにしている。また、MCPやMem0などの最新技術への対応も早く、学習リソースとしての価値も高い。

ただし、このアプローチは開発者に一定のスキルを要求し、「ノーコード」ソリューションを期待するユーザーには適さない。全体として、実用的なAIシステムを構築したい開発者にとって必要不可欠なリソースと言える。