Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kamilbenkirane merged 1 commit into from
Dec 7, 2025
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 147 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,58 +14,97 @@ Primitives, not frameworks.
[![License](https://img.shields.io/badge/License-Apache_2.0-red?style=for-the-badge)](LICENSE)
[![PyPI](https://img.shields.io/badge/PyPI-celeste--ai-green?style=for-the-badge)](https://pypi.org/project/celeste-ai/)

<a href="https://github.com/withceleste/celeste-python" target="_parent">
<img alt="" src="https://img.shields.io/github/stars/withceleste/celeste-python.svg?style=social&label=Star" alt="GitHub stars" />
</a>
<a href="https://pypi.org/project/celeste-ai" target="_parent">
<img alt="" src="https://img.shields.io/pypi/dm/celeste-ai.svg" />
</a>
<a href="https://www.linkedin.com/company/withceleste" target="_parent">
<img src="https://img.shields.io/badge/LinkedIn-Follow%20%40withceleste-0077B5?style=social&logo=linkedin&logoColor=white" alt="Follow @withceleste on LinkedIn"/>
</a>

[Quick Start](#-quick-start) • [Request Provider](https://github.com/withceleste/celeste-python/issues/new)

</div>

---
# Celeste AI

## 🚀 Quick Start

Type-safe, capability-provider-agnostic primitives .

- **Unified Interface:** One API for OpenAI, Anthropic, Gemini, Mistral, and 14+ others.
- **True Multi-Modal:** Text, Image, Audio, Video, Embeddings, Search —all first-class citizens.
- **Type-Safe by Design:** Full Pydantic validation and IDE autocomplete.
- **Zero Lock-In:** Switch providers instantly by changing a single config string.
- **Primitives, Not Frameworks:** No agents, no chains, no magic. Just clean I/O.
- **Lightweight Architecture:** No vendor SDKs. Pure, fast HTTP.

## 🚀 Quick Start
```python
from celeste import create_client, Capability, Provider
from celeste import create_client


# Create client
# "We need a catchy slogan for our new eco-friendly sneaker."
client = create_client(
capability=Capability.TEXT_GENERATION,
provider=Provider.ANTHROPIC,
api_key="your-api-key", # Or loads automatically from environment
capability="text-generation",
model="gpt-5"
)

# Generate
response = await client.generate(prompt="Explain quantum computing")
print(response.content)
```

**Install:**
```bash
uv add "celeste-ai[text-generation]" # Text only
uv add "celeste-ai[image-generation]" # Image generation
uv add "celeste-ai[all]" # Everything
slogan = await client.generate("Write a slogan for an eco-friendly sneaker.")
print(slogan.content)
```

---

## 🎨 Multi-Modal Example

## 🎨 Multimodal example
```python
# Same API, different modalities
text_client = create_client(Capability.TEXT_GENERATION, Provider.ANTHROPIC)
image_client = create_client(Capability.IMAGE_GENERATION, Provider.OPENAI)
video_client = create_client(Capability.VIDEO_GENERATION, Provider.GOOGLE)

text = await text_client.generate(prompt="Write a haiku about AI")
image = await image_client.generate(prompt="A sunset over mountains")
video = await video_client.generate(prompt="Waves crashing on a beach")
from pydantic import BaseModel, Field

class ProductCampaign(BaseModel):
visual_prompt: str
audio_script: str

# 2. Extract Campaign Assets (Anthropic)
# -----------------------------------------------------
extract_client = create_client(Capability.TEXT_GENERATION, model="claude-opus-4-1")
campaign_output = await extract_client.generate(
f"Create campaign assets for slogan: {slogan.content}",
output_schema=ProductCampaign
)
campaign = campaign_output.content

# 3. Generate Ad Visual (Flux)
# -----------------------------------------------------
image_client = create_client(Capability.IMAGE_GENERATION, model="flux-2-dev")
image_output = await image_client.generate(
campaign.visual_prompt,
aspect_ratio="1:1"
)
image = image_output.content

# 4. Generate Radio Spot (ElevenLabs)
# -----------------------------------------------------
speech_client = create_client(Capability.SPEECH_GENERATION, model="eleven_v3")
speech_output = await speech_client.generate(
campaign.audio_script,
voice="adam"
)
speech = speech_output.content
```

No special cases. No separate libraries. **One consistent interface.**

---


---

<div align="center">

## 15+ providers. Zero lock-in.





<img src="https://www.google.com/favicon.ico" width="32" height="32" alt="Google" title="Google">
<img src="https://www.anthropic.com/favicon.ico" width="32" height="32" alt="Anthropic" title="Anthropic">
<img src="https://www.google.com/s2/favicons?domain=openai.com&sz=64" width="32" height="32" alt="OpenAI" title="OpenAI">
Expand All @@ -90,6 +129,84 @@ No special cases. No separate libraries. **One consistent interface.**

---

## 🔄 Switch providers in one line


```python
from pydantic import BaseModel

class User(BaseModel):
name: str
age: int

# Model IDs
anthropic_model_id = "claude-4-5-sonnet"
google_model_id = "gemini-2.5-flash"
```

```python
# ❌ Anthropic Way
from anthropic import Anthropic
import json

client = Anthropic()
response = client.messages.create(
model=anthropic_model_id,
messages=[
{"role": "user",
"content": "Extract user info: John is 30"}
],
output_format={
"type": "json_schema",
"schema": User.model_json_schema()
}
)
user_data = json.loads(response.content[0].text)
```

```python
# ❌ Google Gemini Way
from google import genai
from google.genai import types

client = genai.Client()
response = await client.aio.models.generate_content(
model=gemini_model_id,
contents="Extract user info: John is 30",
config=types.GenerateContentConfig(
response_mime_type="application/json",
response_schema=User
)
)
user = response.parsed
```

```python
# ✅ Celeste Way
from celeste import create_client, Capability


client = create_client(
Capability.TEXT_GENERATION,
model=google_model_id # <--- Choose any model from any provider
)

response = await client.generate(
prompt="Extract user info: John is 30",
output_schema=User # <--- Unified parameter working across all providers
)
user = response.content # Already parsed as User instance
```

---
## 🪶 Install what you need
```bash
uv add "celeste-ai[text-generation]" # Text only
uv add "celeste-ai[image-generation]" # Image generation
uv add "celeste-ai[all]" # Everything
```
---

## 🔧 Type-Safe by Design

```python
Expand Down
Loading