logo

Author: qhoxie

README.md

@@ -44,6 +44,8 @@ Input (messy text)                    →  Output (clean data)
 
 ## Quick Example
 
+> **⚠️ API Key Required**: You need an API key to run LangStruct. **[Get one free here →](https://aistudio.google.com/app/apikey)** or see [setup options](#api-key-setup) below.
+
 ```python
 from langstruct import LangStruct
 
@@ -85,7 +87,32 @@ print(f"Confidence: {result.confidence:.1%}")  # Higher confidence score
 
 ## Quick Start
 
-### Installation
+### 1. Get an API Key (Required)
+
+**Choose one option:**
+
+<div align="center">
+
+| Provider | Free Tier | Get Key | Best For |
+|----------|-----------|---------|----------|
+| 🔥 **Google Gemini** | ✅ Yes | **[Get Free Key →](https://aistudio.google.com/app/apikey)** | **Recommended** - Fast & generous free tier |
+| OpenAI | ❌ Paid | [Get Key →](https://platform.openai.com/api-keys) | Latest models (GPT-4o, o1) |
+| Anthropic | ❌ Paid | [Get Key →](https://console.anthropic.com/) | Claude models |
+| Local (Ollama) | ✅ Free | [Install Ollama →](https://ollama.ai/) | Privacy, no API needed |
+
+</div>
+
+**Set your API key:**
+```bash
+# Recommended: Google Gemini (free)
+export GOOGLE_API_KEY="your-key-here"
+
+# Or use others:
+export OPENAI_API_KEY="your-key-here"
+export ANTHROPIC_API_KEY="your-key-here"
+```
+
+### 2. Installation
 
 Until the first public release, install from source:
 
@@ -121,24 +148,7 @@ pip install langstruct[dev]        # Test and lint toolchain
 pip install langstruct[all]        # Everything above
 ```
 
-### API Key Setup
-
-**Need an API key?** LangStruct auto-detects whichever providers you configure. Common options:
-
-- [Google Gemini API key](https://aistudio.google.com/app/apikey)
-- [OpenAI API key](https://platform.openai.com/api-keys)
-- [Anthropic API key](https://console.anthropic.com/)
-- [Ollama](https://ollama.ai/) for local models (no API key needed)
-
-```bash
-# Set any of these - LangStruct auto-detects the best available model
-export GOOGLE_API_KEY="your-key-here"    # → Uses gemini-2.5-flash
-export OPENAI_API_KEY="your-key-here"    # → Uses gpt-5-mini by default (swap to gpt-5-mini/gpt-5-pro via model=)
-export ANTHROPIC_API_KEY="your-key-here" # → Uses claude-3-5-haiku-latest by default (upgrade to claude-3-7-sonnet-latest/claude-opus-4-1 via model=)
-# Or just install Ollama                 # → Uses llama3
-```
-
-### Basic Usage
+### 3. Basic Usage
 
 ```python
 from langstruct import LangStruct
@@ -352,8 +362,8 @@ for field, spans in result.sources.items():
 
 LangStruct works with any LLM provider:
 
-- **Google Gemini**: gemini/gemini-2.5-flash (recommended - fastest & cheapest), gemini/gemini-2.5-pro
-- **OpenAI**: gpt-5-pro, gpt-5-mini, gpt-4o, gpt-4o-mini (current flagships with great speed/quality options)
+- **Google Gemini**: gemini/gemini-2.5-flash, gemini/gemini-2.5-pro
+- **OpenAI**: gpt-5-pro, gpt-5-mini, gpt-4o, gpt-4o-mini
 - **Anthropic**: claude-opus-4-1, claude-sonnet-4-0, claude-3-7-sonnet-latest, claude-3-5-haiku-latest
 - **Local**: Any model via Ollama (llama3, mistral, etc.)
 
@@ -464,12 +474,75 @@ config = ChunkingConfig(
 
 extractor = LangStruct(
     schema=YourSchema,
-    model="gemini/gemini-2.5-flash",  # Fast & cost-effective
+    model="gemini/gemini-2.5-flash",
     chunking_config=config,
     optimize=True  # Enabled for training data
 )
 ```
 
+## 🔧 Troubleshooting
+
+### API Key Issues
+
+**Error: "No API keys found" or "Authentication failed"**
+
+1. **Check your API key is set:**
+   ```bash
+   echo $GOOGLE_API_KEY  # Should show your key
+   ```
+
+2. **Common fixes:**
+   ```bash
+   # Make sure you're using the right format
+   export GOOGLE_API_KEY="your-actual-key-here"  # No quotes in the key itself
+
+   # For persistent setup, add to your shell profile:
+   echo 'export GOOGLE_API_KEY="your-key"' >> ~/.bashrc
+   source ~/.bashrc
+   ```
+
+3. **Test your key works:**
+   ```python
+   import os
+   print("API key set:", bool(os.getenv("GOOGLE_API_KEY")))
+
+   # Quick test
+   from langstruct import LangStruct
+   ls = LangStruct(example={"name": "test"})
+   result = ls.extract("Hello John")  # Should work without errors
+   ```
+
+**Error: "Model not found" or "Rate limit exceeded"**
+
+- **Model not found**: Your API key might be for a different provider
+- **Rate limits**: Try a different model or wait a few minutes
+- **Billing**: Check your account has credits (OpenAI/Anthropic)
+
+### Installation Issues
+
+**Error: Package not found on PyPI**
+
+LangStruct is currently pre-release. Use the source installation:
+```bash
+git clone https://github.com/langstruct-ai/langstruct.git
+cd langstruct
+uv sync --extra dev
+uv pip install -e .
+```
+
+**Import errors or missing dependencies**
+
+```bash
+# Reinstall with all dependencies
+pip install -e ".[dev,examples,viz,parallel]"
+```
+
+### Getting Help
+
+- 🐛 **Bug reports**: [GitHub Issues](https://github.com/langstruct-ai/langstruct/issues)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/langstruct-ai/langstruct/discussions)
+- 📖 **Documentation**: [langstruct.dev](https://langstruct.dev)
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.