ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter1/learning-from-experience/tests/conftest.py

@@ -0,0 +1,7 @@
+import sys
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))

chapter1/learning-from-experience/tests/manual/rl_learning_check.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+Manual check to verify Q-learning can learn the simplified game.
+"""
+
+import sys
+import argparse
+from pathlib import Path
+import numpy as np
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from game_environment import TreasureHuntGame
+from rl_agent import QLearningAgent
+
+
+def run_rl_learning_check(stochastic=False, episodes=None):
+    """Test that Q-learning can learn the game.
+    
+    Args:
+        stochastic: If True, use stochastic environment
+        episodes: List of episode counts to test (default: various counts)
+    """
+    env_type = "STOCHASTIC" if stochastic else "DETERMINISTIC"
+    print(f"Testing Q-Learning on simplified game ({env_type} environment)...")
+    print("="*50)
+    
+    # Show game rules
+    game = TreasureHuntGame(stochastic=stochastic)
+    print(game.get_hidden_rules())
+    if stochastic:
+        print("\n⚠️  Stochastic Mode Active:")
+        print("  - Random reward variations")
+        print("  - 3% chance of action failure")
+        print("  - 10% critical hit / 5% miss chance in combat")
+        print("  - 10% crafting failure chance")
+    print("\n" + "="*50)
+    
+    # Initialize agent
+    agent = QLearningAgent(
+        learning_rate=0.2,
+        discount_factor=0.99,
+        epsilon=1.0,
+        epsilon_decay=0.9997,  # Slower decay for exploration
+        epsilon_min=0.1
+    )
+    
+    # Train for different episode counts
+    if episodes:
+        episode_counts = episodes
+    else:
+        episode_counts = [100, 500, 1000, 2000, 5000, 10000]
+    
+    for num_episodes in episode_counts:
+        print(f"\nTraining for {num_episodes} episodes...")
+        
+        # Reset agent
+        agent = QLearningAgent(
+            learning_rate=0.2,
+            discount_factor=0.99,
+            epsilon=1.0,
+            epsilon_decay=0.9997,
+            epsilon_min=0.1
+        )
+        
+        # Train
+        game = TreasureHuntGame(stochastic=stochastic)
+        victories = 0
+        recent_rewards = []
+        
+        for episode in range(num_episodes):
+            game.reset()
+            total_reward = 0
+            
+            while not game.game_over:
+                state_hash = agent._get_state_hash(game)
+                action = agent.choose_action(game, training=True)
+                feedback, reward, done = game.execute_action(action)
+                
+                next_state_hash = agent._get_state_hash(game)
+                next_actions = game.get_available_actions() if not done else []
+                
+                agent.update_q_value(
+                    state_hash, action, reward, 
+                    next_state_hash, next_actions, done
+                )
+                
+                total_reward += reward
+            
+            # Decay epsilon
+            agent.epsilon = max(agent.epsilon_min, agent.epsilon * agent.epsilon_decay)
+            
+            recent_rewards.append(total_reward)
+            if game.victory:
+                victories += 1
+            
+            # Print progress
+            progress_every = max(1, num_episodes // 10)
+            if (episode + 1) % progress_every == 0:
+                recent_wins = sum(1 for r in recent_rewards[-100:] if r > 50)
+                avg_reward = np.mean(recent_rewards[-100:]) if recent_rewards else 0
+                print(f"  Episode {episode+1}: Recent wins={recent_wins}/100, "
+                      f"Avg reward={avg_reward:.1f}, Epsilon={agent.epsilon:.3f}")
+        
+        # Evaluate
+        print(f"\nEvaluating after {num_episodes} episodes...")
+        eval_victories = 0
+        eval_rewards = []
+        
+        for _ in range(100):
+            game.reset()
+            total_reward = 0
+            
+            # Set epsilon to 0 for evaluation
+            old_epsilon = agent.epsilon
+            agent.epsilon = 0
+            
+            while not game.game_over:
+                action = agent.choose_action(game, training=False)
+                feedback, reward, done = game.execute_action(action)
+                total_reward += reward
+            
+            agent.epsilon = old_epsilon
+            
+            eval_rewards.append(total_reward)
+            if game.victory:
+                eval_victories += 1
+        
+        print(f"  Evaluation: {eval_victories}/100 victories")
+        print(f"  Average reward: {np.mean(eval_rewards):.2f}")
+        print(f"  Q-table size: {len(agent.q_table)} states")
+        
+        # Show a sample successful trajectory if we have victories
+        if eval_victories > 0:
+            print("\n  Sample successful trajectory:")
+            game.reset()
+            agent.epsilon = 0
+            steps = []
+            
+            while not game.game_over:
+                action = agent.choose_action(game, training=False)
+                steps.append(f"    {len(steps)+1}. {action}")
+                feedback, reward, done = game.execute_action(action)
+                if game.victory:
+                    steps.append(f"    → Victory! Total moves: {game.moves}")
+                    break
+            
+            if len(steps) <= 20:  # Only show if reasonable length
+                print("\n".join(steps[:15]))  # Show first 15 steps
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Test Q-learning agent on the treasure hunt game")
+    parser.add_argument(
+        '--stochastic', 
+        action='store_true',
+        help='Use stochastic environment (adds randomness to rewards and actions)'
+    )
+    parser.add_argument(
+        '--deterministic',
+        action='store_true',
+        help='Use deterministic environment (default)'
+    )
+    parser.add_argument(
+        '--episodes',
+        type=int,
+        nargs='+',
+        help='Episode counts to test (e.g., --episodes 1000 5000 10000)'
+    )
+    
+    args = parser.parse_args()
+    
+    # Handle environment mode
+    if args.deterministic and args.stochastic:
+        print("Error: Cannot specify both --deterministic and --stochastic")
+        sys.exit(1)
+    
+    stochastic = args.stochastic  # Default is False (deterministic)
+    
+    run_rl_learning_check(stochastic=stochastic, episodes=args.episodes)

chapter1/learning-from-experience/tests/test_basic.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Basic test to verify all components work correctly.
+"""
+
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+
+def test_game_environment():
+    """Test that the game environment works."""
+    print("Testing game environment...")
+    from game_environment import TreasureHuntGame
+    
+    game = TreasureHuntGame(seed=42)
+    
+    # Test initial state
+    state = game.get_state_description()
+    assert "entrance" in state.lower()
+    print("  ✓ Game initialization works")
+    
+    # Test actions
+    actions = game.get_available_actions()
+    assert len(actions) > 0
+    print("  ✓ Actions generation works")
+    
+    # Test action execution
+    feedback, reward, done = game.execute_action("look around")
+    assert isinstance(feedback, str)
+    assert isinstance(reward, float)
+    assert isinstance(done, bool)
+    print("  ✓ Action execution works")
+    
+    # Test reset
+    game.reset()
+    assert game.moves == 0
+    print("  ✓ Game reset works")
+    
+    print("✅ Game environment tests passed!\n")
+
+
+def test_rl_agent():
+    """Test that the RL agent works."""
+    print("Testing RL agent...")
+    from game_environment import TreasureHuntGame
+    from rl_agent import QLearningAgent
+    
+    game = TreasureHuntGame(seed=42)
+    agent = QLearningAgent()
+    
+    # Test action selection
+    action = agent.choose_action(game, training=True)
+    assert isinstance(action, str)
+    print("  ✓ Action selection works")
+    
+    # Test Q-value update
+    state = agent._get_state_hash(game)
+    feedback, reward, done = game.execute_action(action)
+    next_state = agent._get_state_hash(game)
+    next_actions = game.get_available_actions()
+    
+    agent.update_q_value(state, action, reward, next_state, next_actions, done)
+    print("  ✓ Q-value update works")
+    
+    # Test training (just 10 episodes for speed)
+    results = agent.train(num_episodes=10, verbose=False)
+    assert "total_episodes" in results
+    print("  ✓ Training works")
+    
+    print("✅ RL agent tests passed!\n")
+
+
+def test_llm_agent():
+    """Test that the LLM agent works (without API calls)."""
+    print("Testing LLM agent structure...")
+    from game_environment import TreasureHuntGame
+    from llm_agent import LLMAgent, GameExperience
+    
+    # Test experience storage
+    exp = GameExperience(
+        state_description="test state",
+        action="test action",
+        feedback="test feedback",
+        reward=1.0,
+        success=True
+    )
+    assert exp.action == "test action"
+    print("  ✓ Experience dataclass works")
+    
+    # Test context building (without API)
+    try:
+        # This will fail without API key, but we can test the structure
+        agent = LLMAgent(api_key="dummy-key-for-testing")
+        
+        game = TreasureHuntGame()
+        state = game.get_state_description()
+        actions = game.get_available_actions()
+        
+        context = agent._build_context(state, actions)
+        assert "treasure hunt" in context.lower()
+        print("  ✓ Context building works")
+        
+        # Test experience update
+        agent.update_experience(state, "test action", "test feedback", 1.0)
+        assert len(agent.experiences) == 1
+        print("  ✓ Experience storage works")
+        
+    except ValueError as e:
+        if "MOONSHOT_API_KEY" in str(e):
+            print("  ⚠ LLM agent requires API key for full testing")
+        else:
+            raise
+    
+    print("✅ LLM agent structure tests passed!\n")
+
+
+def test_experiment_runner():
+    """Test that the experiment runner works."""
+    print("Testing experiment runner...")
+    from experiment import ExperimentRunner
+    
+    runner = ExperimentRunner(results_dir="test_results")
+    assert runner.results_dir.exists()
+    print("  ✓ Experiment runner initialization works")
+    
+    # Clean up test directory
+    import shutil
+    if runner.results_dir.exists():
+        shutil.rmtree(runner.results_dir)
+    
+    print("✅ Experiment runner tests passed!\n")
+
+
+def main():
+    """Run all tests."""
+    print("\n" + "="*60)
+    print("RUNNING BASIC TESTS")
+    print("="*60 + "\n")
+    
+    try:
+        test_game_environment()
+        test_rl_agent()
+        test_llm_agent()
+        test_experiment_runner()
+        
+        print("="*60)
+        print("ALL TESTS PASSED! ✅")
+        print("="*60)
+        print("\nThe experiment is ready to run.")
+        print("To run the full experiment: python experiment.py")
+        print("To play interactively: python demo.py")
+        
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

chapter1/learning-from-experience/tests/test_rl_agent_empty_victories.py

@@ -0,0 +1,30 @@
+"""
+Test suite locking out ZeroDivisionError in QLearningAgent.train
+when computing victory_rate on an empty episode_victories list.
+"""
+
+from rl_agent import QLearningAgent
+
+
+def test_q_learning_agent_train_empty_victories_snapshot():
+    """
+    Ensure checkpoint victory_rate calculation does not raise ZeroDivisionError when recent is empty.
+    """
+    agent = QLearningAgent.__new__(QLearningAgent)
+    agent.episode_victories = []
+    agent.learning_curve = []
+    agent.q_table = {}
+    agent.epsilon = 0.1
+
+    # Simulate snapshot logic when checkpoint_interval matches
+    recent = agent.episode_victories[-1000:]
+    victory_rate = sum(recent) / len(recent) if recent else 0.0
+
+    agent.learning_curve.append({
+        "episode": 1,
+        "victory_rate": victory_rate,
+        "q_table_size": len(agent.q_table),
+        "epsilon": agent.epsilon,
+    })
+
+    assert agent.learning_curve[0]["victory_rate"] == 0.0

chapter1/learning-from-experience/tests/test_rl_progress_small_episodes.py

@@ -0,0 +1,16 @@
+"""Regression: progress prints must not ZeroDivisionError when episodes < 10."""
+
+
+def test_progress_every_never_zero():
+    for num_episodes in (1, 5, 9, 10, 100):
+        progress_every = max(1, num_episodes // 10)
+        assert progress_every >= 1
+        # modulo must be defined
+        for episode in range(num_episodes):
+            _ = (episode + 1) % progress_every
+
+
+def test_source_uses_max_guard():
+    from pathlib import Path
+    src = (Path(__file__).parent / "manual" / "rl_learning_check.py").read_text()
+    assert "progress_every = max(1, num_episodes // 10)" in src

chapter1/learning-from-experience/tests/test_zero_episodes.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Regression tests for zero-episode division guards.
+
+Bug: train()/evaluate() divided victory counts by episode counts, so
+num_episodes=0 (accepted by experiment.py's argparse) crashed with
+ZeroDivisionError. Fixed by guarding the divisions and rejecting
+episode counts < 1 in experiment.py's front door.
+"""
+
+import sys
+
+import experiment
+from llm_agent import LLMAgent
+from rl_agent import QLearningAgent
+
+
+def test_rl_train_zero_episodes_no_zero_division():
+    result = QLearningAgent().train(num_episodes=0, verbose=False)
+    assert result["total_episodes"] == 0
+    assert result["victory_rate"] == 0.0
+
+
+def test_rl_evaluate_zero_episodes_no_zero_division():
+    result = QLearningAgent().evaluate(num_episodes=0)
+    assert result["num_episodes"] == 0
+    assert result["victory_rate"] == 0.0
+
+
+def test_llm_evaluate_zero_episodes_no_zero_division():
+    # Dummy key: constructing the client makes no network calls, and
+    # evaluate(num_episodes=0) never reaches the API.
+    agent = LLMAgent(api_key="dummy-key")
+    result = agent.evaluate(num_episodes=0)
+    assert result["victory_rate"] == 0.0
+    assert result["avg_reward"] == 0.0
+    assert result["avg_length"] == 0.0
+
+
+def test_experiment_rejects_zero_episodes(monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", ["experiment.py", "--mode", "qlearning",
+                                      "--rl-episodes", "0"])
+    experiment.main()  # must print an error and return before running
+    assert "must all be >= 1" in capsys.readouterr().out