A powerful framework for building AI-powered chat applications with FastAPI, SQLAlchemy, and convention over configuration.
🚀 Convention over Configuration • 🤖 AI/Agent Ready • ⚡ FastAPI Powered • �️ Code Generators
Orbin brings productivity and elegance to Python for building AI-powered chat applications. With automatic code generation, database migrations, and RESTful conventions, you can focus on building intelligent agents while Orbin handles the infrastructure.
- 🎯 Powerful Generators: Scaffold models, controllers, and complete CRUD resources
- 🗃️ Database Migrations: Alembic-powered schema management with smart conventions
- 🛣️ RESTful Routing: Automatic route generation with FastAPI
- 🧪 Testing Framework: Auto-generated tests with fixtures
- 🎮 Interactive Console: Developer console with app context
- 📦 Convention over Configuration: Opinionated structure that scales
pip install orbingit clone https://github.com/marceloribeiro/orbin.git
cd orbin
pip install -e .orbin create my_chat_app
cd my_chat_appThis generates a complete FastAPI application structure:
my_chat_app/
├── app/
│ ├── controllers/
│ ├── models/
│ ├── routes/
│ └── main.py
├── config/
├── db/migrations/
├── tests/
└── requirements.txt
PostgreSQL Setup:
# Create PostgreSQL databases (development & test)
orbin db-create
# Run migrations
orbin db-migrate
# Test database connection
orbin db # Opens psql consoleRedis Setup:
# Test Redis connection
orbin redis-ping
# Open Redis console
orbin redis # Opens redis-cli console# Generate a complete CRUD resource (model + controller + tests)
orbin generate scaffold User name:string email:string role:string
# Generate just a model with migration
orbin generate model Message content:text user_id:integer
# Generate a RESTful controller for existing model
orbin generate resource Message
# Generate a custom controller with specific actions
orbin generate controller Chat index show createorbin serverVisit:
- Application: http://localhost:8000
- API Docs: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
orbin create <app_name> # Create new Orbin application
orbin server # Start development server
orbin console # Interactive Python console with app context
orbin test # Run test suite with pytestorbin db-create # Create development and test databases
orbin db-migrate # Run pending migrations
orbin db # Open database console (psql)
orbin db-test-prepare # Prepare test databaseorbin redis-ping # Test Redis connection
orbin redis # Open Redis console (redis-cli)orbin generate scaffold <Model> <attrs> # Complete CRUD (model + controller + tests)
orbin generate model <Model> <attrs> # SQLAlchemy model + migration
orbin generate controller <Name> <actions> # FastAPI controller with actions
orbin generate resource <Model> # RESTful controller for existing model# Create the application
orbin create ai_chat
cd ai_chat
# Set up database and Redis
orbin db-create && orbin db-migrate
orbin redis-ping # Verify Redis connection
# Generate core models
orbin generate scaffold User name:string email:string
orbin generate scaffold Conversation title:string user_id:integer
orbin generate scaffold Message content:text conversation_id:integer role:string
# Run migrations
orbin db-migrate
# Start server
orbin serverChat Features Available:
# In your controllers - Redis-powered features
from config.redis import store_conversation, get_conversation, cache_set
# Cache recent conversations
cache_set(f"recent_conversations:{user_id}", conversations, ttl=300)
# Store real-time conversation context
store_conversation(conversation_id, messages, ttl=86400)
# Pub/sub for real-time updates
redis_client.publish(f"conversation:{conversation_id}", new_message)You now have a complete chat API with:
- Users management:
GET/POST/PUT/DELETE /users - Conversations:
GET/POST/PUT/DELETE /conversations - Messages:
GET/POST/PUT/DELETE /messages - Automatic tests and database fixtures
app/
├── controllers/ # FastAPI route handlers
├── models/ # SQLAlchemy models
└── routes/ # Route definitions
config/
├── database.py # Database configuration
└── settings.py # Application settings
db/migrations/ # Alembic migration files
tests/
├── controllers/ # Controller tests
└── fixtures/ # Test data (YAML)
Orbin automatically generates RESTful endpoints:
| HTTP Verb | Path | Action | Description |
|---|---|---|---|
| GET | /users |
index | List all users |
| GET | /users/{id} |
show | Get specific user |
| POST | /users |
create | Create new user |
| PUT | /users/{id} |
update | Update user |
| DELETE | /users/{id} |
destroy | Delete user |
# Generated User model
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True, index=True)
name = Column(String(255), nullable=False)
email = Column(String(255), nullable=False)
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)Orbin automatically creates comprehensive tests:
# Generated test for User controller
def test_create_user(self):
user_data = {"name": "John Doe", "email": "john@example.com"}
response = self.client.post("/users", json=user_data)
assert response.status_code == 201
assert response.json()["name"] == "John Doe"Orbin is designed for AI applications with built-in patterns for:
- Message-based Communication: Models for conversations, messages, and user interactions
- Agent Workflows: Controllers that can handle AI agent responses
- WebSocket Support: Real-time chat capabilities with FastAPI WebSockets
- Redis Integration: Fast caching, session management, and real-time pub/sub messaging
- Conversation Storage: Efficient Redis-based chat history and context management
- Database Optimizations: Efficient queries for chat history and conversation management
# Store conversation context in Redis
from config.redis import store_conversation, get_conversation
# Cache AI responses
redis_client.cache_set(f"ai_response:{prompt_hash}", response, ttl=3600)
# Real-time notifications
redis_client.publish("chat_updates", json.dumps({"user_id": 123, "message": "New message"}))
# Session management for stateful agents
redis_client.store_user_session("user_123", {"context": "...", "state": "waiting"})Extend Orbin with custom generators:
from orbin.generators.base_generator import BaseGenerator
class MyCustomGenerator(BaseGenerator):
def generate(self):
# Your custom generation logic
pass# Open PostgreSQL console
orbin db
# Common psql commands:
\dt # List tables
\d users # Describe users table
SELECT * FROM users; # Query usersorbin console
# Auto-imports app, settings, database, and models
>>> from app.models.user import User
>>> users = session.query(User).all()
>>> print(f"Total users: {len(users)}")Before starting your Orbin application, you need to set up PostgreSQL and Redis servers.
# macOS
brew install postgresql
brew services start postgresql
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
# Windows
# Download and install from https://www.postgresql.org/download/windows/# macOS
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis-server
# Windows
# Download and install from https://redis.io/download# Application
APP_NAME=MyApp
APP_ENV=development
DEBUG=true
# PostgreSQL Database
DATABASE_URL=postgresql://username:password@localhost:5432/myapp_development
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/myapp_test
# Redis Cache/Session Store
REDIS_URL=redis://localhost:6379/0
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
SECRET_KEY=your-secret-key-change-this-in-productionfrom sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from .settings import settings
engine = create_engine(settings.DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)from orbin.redis_client import get_redis_client
from config.settings import settings
# Get Redis client
redis_client = get_redis_client(settings.REDIS_URL)
# Usage examples
redis_client.cache_set("key", "value", ttl=3600)
redis_client.store_conversation("conv_123", messages)
redis_client.store_user_session("user_456", session_data)# Test PostgreSQL connection
orbin db
# Test Redis connection
orbin redis-ping
# Test full application
orbin server- Python 3.8+
- PostgreSQL 10+ (primary database)
- Redis 6.0+ (caching, sessions, real-time features)
- FastAPI 0.104+
- SQLAlchemy 2.0+
Orbin follows proven conventions adapted for Python:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Controllers │───▶│ Models │───▶│ Database │
│ (FastAPI) │ │ (SQLAlchemy) │ │ (PostgreSQL) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Routes │ │ Migrations │ │ Tests │
│ (Auto-gen) │ │ (Alembic) │ │ (Pytest) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
# Run all tests
orbin test
# Run specific test file
orbin test tests/controllers/test_users_controller.py
# Run with verbose output
orbin test -v
# Skip database preparation (faster for repeated runs)
orbin test --skip-prepare- Generate scaffold:
orbin g scaffold Post title:string content:text - Run migration:
orbin db-migrate - Run tests:
orbin test - Start server:
orbin server - Iterate: Modify controllers, add business logic, enhance tests
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
orbin test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Initial release
- Powerful generators (scaffold, model, controller, resource)
- FastAPI integration with automatic routing
- PostgreSQL database support with Alembic migrations
- Comprehensive testing framework with auto-generated tests
- Interactive console and development server
- Convention over configuration architecture