Initial commit of Python client for GumYum NPC

tests/test_npc_chat_demo.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Demo script showing the new NPC chat functionality
+Run this to see the elegant API in action
+"""
+
+import asyncio
+from gumyum_npc_client import GumYumClient
+
+
+async def demo_npc_chat():
+    """Demonstrate the new NPC chat methods"""
+    # Initialize client
+    client = GumYumClient("http://localhost:8081")
+
+    try:
+        # Authenticate
+        print("🔐 Authenticating...")
+        await client.auth.register("npc_chat_demo", "password123", "demo@example.com")
+
+        # List public universes
+        print("\n🌍 Getting public universes...")
+        public_universes = await client.universes.list_public()
+        if not public_universes:
+            print("No public universes available!")
+            return
+
+        # Copy a universe
+        universe = public_universes[0]
+        print(f"📋 Copying universe: {universe.name}")
+        my_universe_id = await client.universes.copy_public(
+            universe.id, f"My {universe.name}"
+        )
+
+        # Spawn an NPC
+        print("\n🤖 Spawning NPC...")
+        npc = await client.npc.spawn(my_universe_id, seed=42, npc_id=123456)
+        print(f"✨ Spawned: {npc.name} the {npc.profession}")
+
+        # Demonstrate the elegant new API
+        print("\n💬 Chat Method 1: npc.chat.completions()")
+        response = await npc.chat.completions(
+            [{"role": "user", "content": "Hello! Tell me about yourself."}]
+        )
+        print(f"Response: {response.choices[0].message.content}")
+
+        print("\n💬 Chat Method 2: npc.completions() (alias)")
+        response = await npc.completions(
+            [{"role": "user", "content": "What's your favorite thing about your job?"}]
+        )
+        print(f"Response: {response.choices[0].message.content}")
+
+        print("\n💬 Chat Method 3: Streaming")
+        print("Response: ", end="", flush=True)
+        stream = await npc.chat.completions(
+            messages=[
+                {"role": "user", "content": "Tell me a very short story (2 sentences)"}
+            ],
+            stream=True,
+            temperature=0.9,
+        )
+        async for chunk in stream:
+            if "choices" in chunk and chunk["choices"]:
+                delta = chunk["choices"][0].get("delta", {})
+                if "content" in delta:
+                    print(delta["content"], end="", flush=True)
+        print("\n")
+
+        print("\n💬 Chat Method 4: With conversation history")
+        history = [
+            {"role": "user", "content": "My name is Demo User"},
+            {"role": "assistant", "content": "Nice to meet you, Demo User!"},
+            {"role": "user", "content": "What did I just tell you?"},
+        ]
+        response = await npc.completions(history)
+        print(f"Response: {response.choices[0].message.content}")
+
+        # Show that NPCs maintain their own context
+        print("\n🎭 Spawning a second NPC to show context isolation...")
+        npc2 = await client.npc.spawn(my_universe_id, seed=99, npc_id=999999)
+        print(f"✨ Spawned: {npc2.name} the {npc2.profession}")
+
+        # Ask both NPCs the same question
+        print("\n💬 Asking both NPCs: 'What is your name?'")
+        r1 = await npc.completions([{"role": "user", "content": "What is your name?"}])
+        r2 = await npc2.completions([{"role": "user", "content": "What is your name?"}])
+
+        print(f"\n{npc.name} says: {r1.choices[0].message.content}")
+        print(f"\n{npc2.name} says: {r2.choices[0].message.content}")
+
+        print("\n✅ Demo complete! The NPC objects now have elegant chat methods:")
+        print("   - npc.chat.completions(messages) - Full control")
+        print("   - npc.completions(messages) - Convenient alias")
+        print("   - Both support streaming, temperature, max_tokens, etc.")
+        print("   - Each NPC maintains its own context (universe_id, seed, npc_id)")
+
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+
+    finally:
+        await client.close()
+
+
+if __name__ == "__main__":
+    print("🚀 GumYum NPC Chat API Demo")
+    print("=" * 50)
+    asyncio.run(demo_npc_chat())