docs: enhance README with social badges, feature highlights, and provider switching examples

[Kamilbenkirane]

Changes

• Add GitHub stars, PyPI downloads, and LinkedIn follow badges
• Add 'The standard library for AI' section with key features
• Update Quick Start and Multimodal examples
• Add 'Switch providers in one line' comparison section demonstrating Celeste's key differentiator
• Reorganize sections for better flow

Summary

This PR enhances the README to better showcase Celeste's value proposition:

• Social proof badges (stars, downloads, LinkedIn)
• Clear feature highlights
• Practical examples showing provider switching
• Improved structure and readability

[claude]

Pull Request Review: docs/readme-updates

Summary

This PR enhances the README with social proof badges, feature highlights, and provider switching examples. Overall, the documentation improvements are valuable and the content is well-structured. However, there are several critical issues with code accuracy that need to be addressed before merging.

---

🚨 Critical Issues

1. API Inconsistency in Quick Start Example (Line 44-54)

Issue: The Quick Start example uses an incorrect API signature.

Current code:
```python
client = create_client(
capability="text-generation",
model="gpt-5"
)
```

Problem: According to the actual implementation in `src/celeste/init.py:60-65`, the `create_client` function signature is:
```python
def create_client(
capability: Capability,
provider: Provider | None = None,
model: Model | str | None = None,
api_key: SecretStr | None = None,
) -> Client:
```

The `capability` parameter expects a `Capability` enum, not a string. Additionally, when passing a model as a string ID, the `provider` parameter is required (see line 50 in init.py).

Correct code:
```python
from celeste import create_client, Capability, Provider

client = create_client(
capability=Capability.TEXT_GENERATION,
provider=Provider.OPENAI,
model="gpt-5"
)
```

Or with string capability if the API supports it (verify this):
```python
client = create_client(
capability="text-generation",
provider="openai",
model="gpt-5"
)
```

Location: README.md:44-54

---

2. Missing Import in Multimodal Example (Line 58-92)

Issue: The multimodal example references `Capability` without importing it.

Current code (line 68):
```python
extract_client = create_client(Capability.TEXT_GENERATION, model="claude-opus-4-1")
```

Problem: `Capability` is used but not imported. The imports only show:
```python
from pydantic import BaseModel, Field
```

Fix: Add the missing import:
```python
from celeste import create_client, Capability
from pydantic import BaseModel, Field
```

Location: README.md:59-60

---

3. Inconsistent Code Examples in Provider Comparison (Line 132-199)

Issue: The "Celeste Way" example shows inconsistent parameter usage compared to the Quick Start.

Current code (line 189-192):
```python
client = create_client(
Capability.TEXT_GENERATION,
model=google_model_id # <--- Choose any model from any provider
)
```

Problem:

1. This uses positional arguments for `capability`, but the function signature requires a keyword argument based on Python best practices
2. Missing `provider` parameter, which is required when `model` is a string ID (see init.py:49-51)
3. The comment says "Choose any model from any provider" but `google_model_id` is defined as `"gemini-2.5-flash"` (line 144), which is Google-specific

Fix:
```python
client = create_client(
capability=Capability.TEXT_GENERATION,
provider=Provider.GOOGLE,
model=google_model_id # <--- Choose any model from any provider
)
```

Location: README.md:189-192

---

⚠️ Medium Priority Issues

4. Undefined Variable Reference (Line 53)

Issue: `slogan` variable used in line 69 is only available if Quick Start code runs first.

Current code:
```python
campaign_output = await extract_client.generate(
f"Create campaign assets for slogan: {slogan.content}",
output_schema=ProductCampaign
)
```

Problem: The multimodal example references `slogan.content` from the Quick Start example, but they appear to be separate code blocks. This would cause a `NameError` if run independently.

Recommendation: Either:

1. Make it clear these examples are sequential, or
2. Define `slogan` within the multimodal example

Location: README.md:69

---

5. Missing Context About Model IDs (Line 52)

Issue: The Quick Start uses `model="gpt-5"` without explanation.

Problem: "gpt-5" doesn't exist (as of January 2025). This could confuse users. Consider using:

• An actual model ID like `"gpt-4-turbo"` or `"gpt-4"`
• A placeholder like `"gpt-4"` with a comment explaining users should check available models
• Adding a note about using `list_models()` to see available options

Location: README.md:52

---

6. Trailing Period in Description (Line 34)

Issue: Grammatical error - sentence fragment with trailing period.

Current: `Type-safe, capability-provider-agnostic primitives .`

Fix: `Type-safe, capability-provider-agnostic primitives.`

Location: README.md:34

---

✅ Positive Aspects

1. Great Value Proposition: The "Switch providers in one line" comparison effectively demonstrates Celeste's key differentiator
2. Well-Structured: Logical flow from Quick Start → Multimodal → Provider Comparison → Installation
3. Social Proof: Badge additions are appropriate and properly formatted
4. Practical Examples: The multimodal campaign generation example is realistic and compelling
5. Clear Differentiation: The side-by-side comparison with Anthropic and Google SDKs clearly shows the value

---

📋 Recommendations

High Priority (Block Merge)

• Fix API signature in Quick Start example (Issue Add Claude Code GitHub Workflow #1)
• Add missing import in Multimodal example (Issue Add Claude Code GitHub Workflow #2)
• Fix provider parameter in comparison section (Issue chore: setup repository infrastructure #3)

Medium Priority (Should Fix)

• Resolve undefined variable issue in Multimodal example (Issue chore: setup repository infrastructure #4)
• Use realistic model ID or explain placeholder (Issue docs: add .env.example file for credential configuration #5)
• Fix trailing period typo (Issue feat: add artifacts and mime_types core modules #6)

Nice to Have

• Consider adding a note about environment variable setup for API keys
• Add a comment showing how users can discover available models via `list_models()`
• Consider adding async context to the Quick Start (showing `async def main()` wrapper)

---

Testing Checklist

Before merging, please verify:

• All code examples run without modification (copy-paste should work)
• Imports are complete and correct
• Model IDs referenced actually exist or are clearly marked as examples
• Variables referenced are defined in scope
• API signatures match the actual implementation

---

Conclusion

This PR significantly improves the README's marketing and educational value. However, the code examples contain critical accuracy issues that will confuse users and potentially generate support tickets. Please address the high-priority issues before merging.

The examples should be executable without modification - this is crucial for a library that emphasizes ease of use and developer experience.

🔧 Generated with Claude Code