# VibeDB

**SQLite-based document database for rapid prototyping**

VibeDB combines SQLite's simplicity with MongoDB's document flexibility. Zero config, zero dependencies, instant start.

## Installation

```bash
# Core only (zero dependencies)
pip install vibedb

# With Studio UI (includes Flask)
pip install vibedb[all]
```

## Quick Start (30 seconds)

```python
from vibedb import VibeDB, Q

# Create database
db = VibeDB("app.db")
users = db.collection("users")

# Insert
user_id = users.insert({"name": "Alice", "email": "alice@example.com", "age": 28})

# Query
results = users.find(Q.gte("age", 25) & Q.contains("email", "@example.com"))

# Update
users.update(user_id, {"age": 29})

# Index for performance
users.create_index(["email"], unique=True)

# Launch Studio UI
db.studio(port=5000)
```

## For AI Agents

If you're an AI agent helping users with VibeDB, use these skills:

- `/vibedb-quickstart` - Start here: basic CRUD, queries, common operations
- `/vibedb-indexing` - Performance: create indexes, auto-suggestions, optimization
- `/vibedb-patterns` - Production patterns: caching, sessions, job queues, etc.

Skills are in `skills/` folder with progressive disclosure (SKILL.md → reference.md → examples.md).

## Features

- **Zero Config**: Works immediately after install
- **Document Freedom**: Store JSON without schemas (add validation later)
- **Dual Query Syntax**: MongoDB-style dicts OR Pythonic Q builder
- **Auto-Index Hints**: Suggests indexes based on slow queries
- **Studio UI**: Web-based database explorer and query playground

## Examples

Complete working examples in `examples/`:
- **quickstart.py** - Todo app in 10 lines
- **blog_app.py** - Blog with posts, comments, and full-text search
- **ecommerce.py** - Products, orders, and inventory tracking

## Documentation

- **API Reference**: See `skills/vibedb-quickstart/reference.md`
- **Usage Examples**: See `skills/vibedb-quickstart/examples.md`
- **Production Patterns**: See `skills/vibedb-patterns/SKILL.md`
- **Performance Guide**: See `skills/vibedb-indexing/SKILL.md`

## Philosophy

Built for **vibe coders** - developers who want rapid iteration:
- Start schema-less, validate later
- Auto-suggest but don't force
- Great errors with helpful hints
- Studio UI for visual debugging

## Comparison to Alternatives

| Feature | VibeDB | MongoDB | SQLite |
|---------|---------|---------|--------|
| Setup | Zero config | Server required | File-based |
| Schema | Optional | Optional | Required |
| Query API | Dict + Builder | Dict only | SQL only |
| Web UI | Built-in | Separate | None |
| Dependencies | Zero | Many | Zero |
| Best For | Prototyping | Production | Embedded |

## License

MIT License - see [LICENSE](LICENSE)

## Links

- **GitHub**: https://github.com/StevenSLXie/vibeDB
- **PyPI**: https://pypi.org/project/vibedb/
- **Skills**: [skills/README.md](skills/README.md)
- **Examples**: [examples/](examples/)
