feat: Onboarding guidance with .env setup

agents-core/README.md

@@ -10,4 +10,50 @@ Build Vision Agents quickly with any model or video provider.
 
 Created by Stream, uses [Stream's edge network](https://getstream.io/video/) for ultra-low latency.
 
-See [Github](https://github.com/GetStream/Vision-Agents).
+## Quick Start
+
+```bash
+# Install vision-agents
+uv add vision-agents
+
+# Import (automatically creates .env file)
+python -c "from vision_agents import Agent"
+```
+
+The package automatically creates a `.env` file with example configuration. Edit it to add your API keys:
+
+### Required API Keys
+- **Stream** (required): `STREAM_API_KEY`, `STREAM_API_SECRET` - [Get keys](https://getstream.io/)
+- **LLM** (choose one): `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY`
+- **STT** (choose one): `DEEPGRAM_API_KEY`, `MOONSHINE_API_KEY`, `WIZPER_API_KEY`
+- **TTS** (choose one): `CARTESIA_API_KEY`, `ELEVENLABS_API_KEY`, `KOKORO_API_KEY`
+- **Turn Detection**: `FAL_KEY` - [Get key](https://fal.ai/)
+
+### Setup Commands
+```bash
+vision-agents-setup              # Create .env file
+vision-agents-setup --guide      # Show setup guide
+vision-agents-setup --force      # Overwrite existing .env
+```
+
+## Example Usage
+
+```python
+from vision_agents import Agent
+from vision_agents.plugins import openai, deepgram, cartesia
+
+agent = Agent(
+    edge=getstream.Edge(),
+    agent_user=User(name="AI Assistant", id="agent"),
+    instructions="You're a helpful AI assistant.",
+    llm=openai.LLM(model="gpt-4o-mini"),
+    tts=cartesia.TTS(),
+    stt=deepgram.STT(),
+)
+```
+
+## Documentation
+
+- 📚 [Full Documentation](https://visionagents.ai/)
+- 💬 [Examples](https://github.com/GetStream/Vision-Agents/tree/main/examples)
+- 🔧 [GitHub Repository](https://github.com/GetStream/Vision-Agents)

agents-core/pyproject.toml

@@ -81,6 +81,9 @@ packages = ["vision_agents"]
 [tool.hatch.build.targets.sdist]
 include = ["vision_agents"]
 
+[project.scripts]
+vision-agents-setup = "vision_agents.post_install:main"
+
 #[tool.uv.sources]
 #krisp-audio = [
 #    { path = "./vision_agents/core/turn_detection/krisp/krisp_audio-1.4.0-cp313-cp313-macosx_12_0_arm64.whl", marker = "sys_platform == 'darwin' and platform_machine == 'aarch64'" },

agents-core/vision_agents/__init__.py

@@ -0,0 +1,61 @@
+"""
+Vision Agents - Open video agents for building low latency video and voice agents.
+"""
+
+from pathlib import Path
+
+# Version will be set by hatch-vcs
+__version__ = "0.0.0"
+
+# Auto-create .env file on first import if it doesn't exist
+def _setup_env_file():
+    """Automatically create .env file from template if it doesn't exist."""
+    try:
+        # Get the package directory
+        package_dir = Path(__file__).parent
+
+        # Template file path
+        template_path = package_dir / "env_template.txt"
+
+        # Target .env file path (in current working directory)
+        env_path = Path.cwd() / ".env"
+
+        # Check if .env already exists
+        if env_path.exists():
+            return
+
+        # Check if template exists
+        if not template_path.exists():
+            return
+
+        # Only create .env if we're in a project directory (not in site-packages)
+        # This prevents creating .env files in unexpected places
+        if "site-packages" in str(package_dir) or "dist-packages" in str(package_dir):
+            return
+
+        # Copy template to .env
+        import shutil
+        shutil.copy2(template_path, env_path)
+
+        # Print helpful message
+        print("🎉 Vision Agents: Created .env file with example configuration!")
+        print()
+        print("📁 File location:")
+        print(f"   {env_path.absolute()}")
+        print()
+        print("📝 Please edit the .env file and add your actual API keys")
+        print("🔗 See the comments in the .env file for where to get API keys")
+        print("💡 Run 'vision-agents-setup' command for more setup options")
+
+    except Exception:
+        # Silently fail - don't break the import if env setup fails
+        pass
+
+# Run the setup function
+_setup_env_file()
+
+# Import core components
+from .core.agents import Agent
+from .core.edge.types import User
+
+__all__ = ["Agent", "User", "__version__"]

agents-core/vision_agents/env_template.txt

@@ -0,0 +1,129 @@
+# Vision Agents Environment Configuration
+# Copy this file to .env and fill in your actual API keys
+
+# =============================================================================
+# CORE INFRASTRUCTURE
+# =============================================================================
+
+# Stream (Required for video/audio infrastructure)
+# Get your keys from: https://getstream.io/
+STREAM_API_KEY=your_stream_api_key_here
+STREAM_API_SECRET=your_stream_api_secret_here
+STREAM_BASE_URL=https://getstream.io
+
+# =============================================================================
+# LLM PROVIDERS
+# =============================================================================
+
+# OpenAI (for GPT models)
+# Get your key from: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Google/Gemini
+# Get your key from: https://aistudio.google.com/app/apikey
+GOOGLE_API_KEY=your_google_api_key_here
+GEMINI_API_KEY=your_gemini_api_key_here  # Alternative to GOOGLE_API_KEY
+
+# Anthropic (Claude)
+# Get your key from: https://console.anthropic.com/
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# xAI (Grok)
+# Get your key from: https://console.x.ai/
+XAI_API_KEY=your_xai_api_key_here
+
+# =============================================================================
+# SPEECH-TO-TEXT (STT) PROVIDERS
+# =============================================================================
+
+# Deepgram
+# Get your key from: https://console.deepgram.com/
+DEEPGRAM_API_KEY=your_deepgram_api_key_here
+
+# Moonshine
+# Get your key from: https://moonshine.ai/
+MOONSHINE_API_KEY=your_moonshine_api_key_here
+
+# Wizper
+# Get your key from: https://wizper.ai/
+WIZPER_API_KEY=your_wizper_api_key_here
+
+# =============================================================================
+# TEXT-TO-SPEECH (TTS) PROVIDERS
+# =============================================================================
+
+# Cartesia
+# Get your key from: https://cartesia.ai/
+CARTESIA_API_KEY=your_cartesia_api_key_here
+
+# ElevenLabs
+# Get your key from: https://elevenlabs.io/
+ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
+
+# Kokoro
+# Get your key from: https://kokoro.ai/
+KOKORO_API_KEY=your_kokoro_api_key_here
+
+# =============================================================================
+# TURN DETECTION & VAD
+# =============================================================================
+
+# Smart Turn (FAL)
+# Get your key from: https://fal.ai/
+FAL_KEY=your_fal_api_key_here
+
+# =============================================================================
+# COMPUTER VISION
+# =============================================================================
+
+# Ultralytics (YOLO models)
+# No API key required for basic usage
+# ULTRALYTICS_API_KEY=your_ultralytics_api_key_here
+
+# =============================================================================
+# AUDIO PROCESSING
+# =============================================================================
+
+# Krisp (Noise cancellation)
+# Get your key from: https://krisp.ai/
+KRISP_API_KEY=your_krisp_api_key_here
+
+# =============================================================================
+# MCP (Model Context Protocol) SERVERS
+# =============================================================================
+
+# Local MCP server command (for testing)
+MCP_LOCAL_CMD=python -m mcp_server_weather
+
+# Remote MCP server URL (for testing)
+MCP_REMOTE_URL=https://your-mcp-server.com
+
+# MCP server headers (prefix with MCP_REMOTE_HEADERS_)
+# MCP_REMOTE_HEADERS_Authorization=Bearer your_token
+# MCP_REMOTE_HEADERS_X_API_Key=your_api_key
+
+# =============================================================================
+# DEVELOPMENT & TESTING
+# =============================================================================
+
+# Example base URL for demos
+EXAMPLE_BASE_URL=https://getstream.io/video/demos
+
+# Test configuration
+TEST_MCP_CITY=New York
+
+# GitHub (for MCP integration tests)
+GITHUB_PAT=your_github_personal_access_token_here
+
+# =============================================================================
+# OPTIONAL CONFIGURATION
+# =============================================================================
+
+# OpenAI model selection
+OPENAI_MODEL=gpt-4o-mini
+
+# Logging level
+LOG_LEVEL=INFO
+
+# Debug mode
+DEBUG=false

agents-core/vision_agents/post_install.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Vision Agents Setup Script
+Creates a .env file from template and provides setup guidance.
+"""
+
+import sys
+import shutil
+import argparse
+from pathlib import Path
+
+
+def create_env_file(target_dir=None, force=False):
+    """Create .env file from template if it doesn't exist."""
+    # Get the package directory
+    package_dir = Path(__file__).parent
+
+    # Template file path
+    template_path = package_dir / "env_template.txt"
+
+    # Target directory
+    if target_dir is None:
+        target_dir = Path.cwd()
+    else:
+        target_dir = Path(target_dir)
+
+    # Target .env file path
+    env_path = target_dir / ".env"
+
+    # Check if .env already exists
+    if env_path.exists() and not force:
+        print(f"✓ .env file already exists at {env_path}")
+        print("💡 Use --force to overwrite existing .env file")
+        return True
+
+    # Check if template exists
+    if not template_path.exists():
+        print(f"❌ Template file not found at {template_path}")
+        return False
+
+    try:
+        # Ensure target directory exists
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        # Copy template to .env
+        shutil.copy2(template_path, env_path)
+        print(f"✓ Created .env file at: {env_path}")
+        print()
+        print("📁 File location:")
+        print(f"   {env_path.absolute()}")
+        print()
+        print("📝 Next steps:")
+        print("1. Edit the .env file and add your actual API keys")
+        print("2. See the comments in the .env file for where to get API keys")
+        print("3. Start building your vision agent!")
+        print()
+        print("🔗 Quick links for API keys:")
+        print("  • Stream: https://getstream.io/")
+        print("  • OpenAI: https://platform.openai.com/api-keys")
+        print("  • Deepgram: https://console.deepgram.com/")
+        print("  • Cartesia: https://cartesia.ai/")
+        print("  • FAL (Smart Turn): https://fal.ai/")
+        return True
+
+    except Exception as e:
+        print(f"❌ Failed to create .env file: {e}")
+        return False
+
+
+def show_setup_guide():
+    """Show comprehensive setup guide."""
+    print("🚀 Vision Agents Setup Guide")
+    print("=" * 50)
+    print()
+    print("✅ Package already installed!")
+    print()
+    print("📝 Next steps:")
+    print("1. Add your API keys to the .env file")
+    print("2. Start building your vision agent:")
+    print()
+    print("   from vision_agents import Agent")
+    print("   from vision_agents.plugins import openai, deepgram, cartesia")
+    print()
+    print("🔧 Setup commands:")
+    print("   vision-agents-setup              # Create .env file")
+    print("   vision-agents-setup --force      # Overwrite existing .env")
+    print("   vision-agents-setup --guide      # Show this guide")
+    print()
+    print("📚 Documentation: https://visionagents.ai/")
+    print("💬 Examples: https://github.com/GetStream/Vision-Agents/tree/main/examples")
+
+
+def main():
+    """Main entry point for setup script."""
+    parser = argparse.ArgumentParser(
+        description="Vision Agents setup script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  vision-agents-setup                    # Create .env in current directory
+  vision-agents-setup --dir /path/to/project  # Create .env in specific directory
+  vision-agents-setup --force           # Overwrite existing .env file
+  vision-agents-setup --guide           # Show setup guide
+        """
+    )
+
+    parser.add_argument(
+        "--dir", "-d",
+        help="Directory to create .env file in (default: current directory)"
+    )
+
+    parser.add_argument(
+        "--force", "-f",
+        action="store_true",
+        help="Overwrite existing .env file"
+    )
+
+    parser.add_argument(
+        "--guide", "-g",
+        action="store_true",
+        help="Show setup guide"
+    )
+
+    args = parser.parse_args()
+
+    if args.guide:
+        show_setup_guide()
+        return
+
+    try:
+        success = create_env_file(target_dir=args.dir, force=args.force)
+        if not success:
+            sys.exit(1)
+    except Exception as e:
+        print(f"❌ Setup script failed: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()