@totaland/create-starter-kit 2.0.4 → 2.0.7

package/bin/index.js

@@ -20,8 +20,9 @@ const templateArg = process.argv[3]; // Optional template argument
 
 if (!projectName) {
     console.error('Error: Please provide a project name');
-    console.log('Usage: pnpm create @totaland/starter-kit <project-name> [template]');
-    console.log('Templates: backend, frontend, fullstack');
+    console.log('Usage: pnpm create @totaland/create-starter-kit <project-name> [template]');
+    console.log('       create-starter-kit <project-name> [template]');
+    console.log('Templates: backend, frontend, fullstack, python-backend, ai-fullstack');
     process.exit(1);
 }
 
@@ -47,11 +48,23 @@ const TEMPLATES = {
         description: 'React + Vite with TypeScript, Tailwind CSS v4, shadcn/ui, and TanStack Query',
         dir: 'frontend',
     },
+    'python-backend': {
+        name: 'Python AI Backend',
+        description: 'FastAPI + LangGraph + OpenAI/Anthropic for AI orchestration',
+        dir: 'python-backend',
+        isPython: true,
+    },
     fullstack: {
         name: 'Fullstack',
         description: 'Both Backend and Frontend templates combined',
         dirs: ['backend', 'frontend'],
     },
+    'ai-fullstack': {
+        name: 'AI Fullstack',
+        description: 'Python AI Backend + React Frontend',
+        dirs: ['python-backend', 'frontend'],
+        isPython: true,
+    },
 };
 
 // Directories and files to exclude when copying
@@ -69,6 +82,14 @@ const EXCLUDE = new Set([
     '.env',
     '.env.local',
     '.DS_Store',
+    // Python exclusions
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.ruff_cache',
+    '.eggs',
 ]);
 
 // Function to recursively copy directory
@@ -102,22 +123,32 @@ async function promptTemplate() {
     });
 
     console.log('\n📦 Select a template:\n');
-    console.log('1. Backend   - Express.js + TypeScript + Drizzle ORM');
-    console.log('2. Frontend  - React + Vite + Tailwind CSS v4 + shadcn/ui');
-    console.log('3. Fullstack - Both Backend and Frontend\n');
+    console.log('1. Backend        - Express.js + TypeScript + Drizzle ORM');
+    console.log('2. Frontend       - React + Vite + Tailwind CSS v4 + shadcn/ui');
+    console.log('3. Fullstack      - Backend + Frontend');
+    console.log('4. Python Backend - FastAPI + LangGraph + OpenAI/Anthropic (AI)');
+    console.log('5. AI Fullstack   - Python Backend + Frontend\n');
 
-    const answer = await rl.question('Enter your choice (1, 2, or 3): ');
+    const answer = await rl.question('Enter your choice (1-5): ');
     rl.close();
 
-    if (answer === '1' || answer.toLowerCase() === 'backend') {
-        return 'backend';
-    }
-    if (answer === '2' || answer.toLowerCase() === 'frontend') {
-        return 'frontend';
-    }
-    if (answer === '3' || answer.toLowerCase() === 'fullstack') {
-        return 'fullstack';
-    }
+    const choices = {
+        '1': 'backend',
+        'backend': 'backend',
+        '2': 'frontend',
+        'frontend': 'frontend',
+        '3': 'fullstack',
+        'fullstack': 'fullstack',
+        '4': 'python-backend',
+        'python-backend': 'python-backend',
+        'python': 'python-backend',
+        '5': 'ai-fullstack',
+        'ai-fullstack': 'ai-fullstack',
+        'ai': 'ai-fullstack',
+    };
+
+    const choice = choices[answer.toLowerCase()];
+    if (choice) return choice;
 
     console.error('Invalid choice. Please run the command again.');
     process.exit(1);
@@ -133,7 +164,7 @@ async function main() {
             templateKey = templateArg.toLowerCase();
             if (!TEMPLATES[templateKey]) {
                 console.error(`Error: Invalid template "${templateArg}"`);
-                console.log('Available templates: backend, frontend, fullstack');
+                console.log('Available templates: backend, frontend, fullstack, python-backend, ai-fullstack');
                 process.exit(1);
             }
         } else {
@@ -187,19 +218,34 @@ async function main() {
         console.log('✅ Project created successfully!\n');
         console.log('📝 Next steps:');
         console.log(`   cd ${projectName}`);
+        
         if (templateKey === 'fullstack') {
             console.log('   cd backend && pnpm install && pnpm dev');
             console.log('   cd frontend && pnpm install && pnpm dev\n');
+        } else if (templateKey === 'ai-fullstack') {
+            console.log('   cd python-backend && pip install -e ".[dev]" && uvicorn src.main:app --reload');
+            console.log('   cd frontend && pnpm install && pnpm dev\n');
+        } else if (template.isPython) {
+            console.log('   python -m venv .venv && source .venv/bin/activate');
+            console.log('   pip install -e ".[dev]"');
+            console.log('   cp .env.example .env  # Add your API keys');
+            console.log('   uvicorn src.main:app --reload\n');
         } else {
             console.log('   pnpm install');
             console.log('   pnpm dev\n');
         }
 
-        if (templateKey === 'frontend' || templateKey === 'fullstack') {
+        if (templateKey === 'frontend' || templateKey === 'fullstack' || templateKey === 'ai-fullstack') {
             console.log('💡 Tip: Add shadcn/ui components with:');
-            const cdPath = templateKey === 'fullstack' ? 'cd frontend && ' : '';
+            const cdPath = (templateKey === 'fullstack' || templateKey === 'ai-fullstack') ? 'cd frontend && ' : '';
             console.log(`   ${cdPath}pnpm dlx shadcn@latest add button card dialog\n`);
         }
+
+        if (template.isPython) {
+            console.log('🤖 AI Setup: Add your API keys to .env:');
+            console.log('   OPENAI_API_KEY=sk-...');
+            console.log('   ANTHROPIC_API_KEY=sk-ant-...\n');
+        }
     } catch (error) {
         console.error('Error creating project:', error.message);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totaland/create-starter-kit",
-  "version": "2.0.4",
+  "version": "2.0.7",
   "description": "Scaffolding tool for creating new starter-kit projects",
   "type": "module",
   "publishConfig": {

package/templates/python-backend/.env.example

@@ -0,0 +1,36 @@
+APP_NAME="AI Starter Kit"
+DEBUG=true
+
+# Database
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/app
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# ===== AI / LLM Configuration =====
+
+# OpenAI - https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+
+# Anthropic - https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+
+# Default LLM provider: "openai" or "anthropic"
+DEFAULT_LLM_PROVIDER=openai
+
+# LangSmith (optional) - https://smith.langchain.com/
+LANGSMITH_API_KEY=lsv2_...
+LANGSMITH_PROJECT=ai-starter-kit
+LANGSMITH_TRACING=false
+
+# LLM Settings
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=4096
+LLM_STREAMING=true

package/templates/python-backend/Makefile

@@ -0,0 +1,26 @@
+.PHONY: install dev test lint format typecheck clean
+
+install:
+	pip install -e ".[dev]"
+
+dev:
+	uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+
+test:
+	pytest
+
+test-cov:
+	pytest --cov=src --cov-report=html
+
+lint:
+	ruff check src tests
+
+format:
+	ruff format src tests
+
+typecheck:
+	mypy src
+
+clean:
+	rm -rf __pycache__ .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage
+	find . -type d -name "__pycache__" -exec rm -rf {} +

package/templates/python-backend/README.md

@@ -0,0 +1,123 @@
+# AI Starter Kit
+
+Production-ready Python backend for AI application orchestration with LangGraph, OpenAI, and Anthropic.
+
+## AI / LLM Features
+
+| Feature | Description |
+|---------|-------------|
+| **LangGraph** | State machine orchestration for multi-step AI agents |
+| **Multi-provider LLMs** | OpenAI (GPT-4o) and Anthropic (Claude) with easy switching |
+| **Streaming** | Server-Sent Events for real-time token streaming |
+| **Tool calling** | Built-in tool execution with ReAct agent pattern |
+| **LangSmith** | Optional tracing and observability integration |
+| **Memory** | Conversation memory with checkpointing |
+
+## Performance Packages Included
+
+| Package | Purpose | Why It's Fast |
+|---------|---------|---------------|
+| **FastAPI** | Web framework | Built on Starlette, async-first, fastest Python framework |
+| **uvicorn** | ASGI server | Uses uvloop (libuv-based event loop) |
+| **orjson** | JSON serialization | Written in Rust, 3-10x faster than stdlib json |
+| **msgspec** | Serialization/validation | Zero-copy deserialization, faster than Pydantic |
+| **polars** | DataFrames | Rust-based, multithreaded, lazy evaluation |
+| **asyncpg** | PostgreSQL driver | Native async, fastest Python PostgreSQL driver |
+| **pendulum** | Date/time | Drop-in datetime replacement with better perf |
+| **httpx** | HTTP client | Async support, HTTP/2 support |
+| **structlog** | Logging | Structured logging with minimal overhead |
+
+## Quick Start
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Copy environment file
+cp .env.example .env
+
+# Run development server
+uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+## Project Structure
+
+```
+python-backend/
+├── src/
+│   ├── features/           # Feature-based organization
+│   │   ├── agents/         # LangGraph agent workflows
+│   │   ├── chat/           # Chat completion endpoints
+│   │   ├── health/         # Health check endpoints
+│   │   └── orders/         # Order management example
+│   ├── lib/                # Shared utilities
+│   │   ├── agents.py       # LangGraph agent builder & tools
+│   │   ├── cache.py        # In-memory caching
+│   │   ├── database.py     # Async SQLAlchemy setup
+│   │   ├── llm.py          # LLM provider abstraction
+│   │   └── logging.py      # Structured logging
+│   ├── config.py           # Settings via pydantic-settings
+│   └── main.py             # Application entry point
+├── tests/                  # Test files
+├── pyproject.toml          # Dependencies & tool config
+└── .env.example            # Environment template
+```
+
+## Development Commands
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=src --cov-report=html
+
+# Type checking
+mypy src
+
+# Linting & formatting
+ruff check src tests
+ruff format src tests
+
+# Run with auto-reload
+uvicorn src.main:app --reload
+```
+
+## API Endpoints
+
+### Chat Completions
+```bash
+# Streaming chat (SSE)
+curl -X POST http://localhost:8000/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"messages": [{"role": "user", "content": "Hello!"}], "stream": true}'
+
+# Non-streaming chat
+curl -X POST http://localhost:8000/chat/completions/sync \
+  -H "Content-Type: application/json" \
+  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'
+```
+
+### Agent Workflows
+```bash
+# Invoke agent with tools
+curl -X POST http://localhost:8000/agents/invoke \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What time is it and calculate 42 * 17?"}'
+
+# List available tools
+curl http://localhost:8000/agents/tools
+```
+
+## API Documentation
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## License
+
+MIT

package/templates/python-backend/pyproject.toml

@@ -0,0 +1,143 @@
+[project]
+name = "python-starter-kit"
+version = "1.0.0"
+description = "AI-powered Python backend with LangGraph orchestration"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    # Web Framework - fastest Python web framework
+    "fastapi>=0.129.0",
+    
+    # ASGI Server - high performance
+    "uvicorn[standard]>=0.41.0",
+    
+    # Fast JSON serialization/deserialization
+    "orjson>=3.11.7",
+    
+    # Ultra-fast serialization library (faster than pydantic for many cases)
+    "msgspec>=0.20.0",
+    
+    # High-performance DataFrame library (faster than pandas)
+    "polars>=1.38.1",
+    
+    # Async PostgreSQL driver
+    "asyncpg>=0.31.0",
+    
+    # Async SQLAlchemy ORM
+    "sqlalchemy[asyncio]>=2.0.46",
+    
+    # Environment variables
+    "python-dotenv>=1.2.1",
+    
+    # Data validation (Pydantic v2 with Rust core)
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.0",
+    
+    # Caching with Redis
+    "redis>=7.2.0",
+    
+    # HTTP client (async)
+    "httpx>=0.28.1",
+    
+    # Date/time handling (faster than datetime)
+    "pendulum>=3.2.0",
+    
+    # LRU cache with TTL
+    "cachetools>=7.0.1",
+    
+    # Structured logging
+    "structlog>=25.5.0",
+    
+    # ===== AI / LLM Orchestration =====
+    # LangGraph - state machine orchestration for AI agents
+    "langgraph>=1.0.8",
+    
+    # LangChain core abstractions
+    "langchain>=1.2.10",
+    "langchain-core>=1.2.13",
+    
+    # LLM Providers
+    "langchain-openai>=1.1.10",
+    "langchain-anthropic>=1.3.3",
+    "openai>=2.21.0",
+    "anthropic>=0.39.0",
+    
+    # LangSmith for tracing & observability
+    "langsmith>=0.1.140",
+    
+    # Embeddings & Vector stores
+    "langchain-community>=0.3.0",
+    
+    # Tiktoken for token counting
+    "tiktoken>=0.8.0",
+    
+    # Server-Sent Events for streaming
+    "sse-starlette>=3.2.0",
+    
+    # Tenacity for retry logic
+    "tenacity>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    # Testing
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "httpx>=0.28.0",
+    
+    # Type checking
+    "mypy>=1.13.0",
+    
+    # Linting & Formatting
+    "ruff>=0.8.0",
+    
+    # Hot reload for development
+    "watchfiles>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]

package/templates/python-backend/src/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-backend/src/config.py

@@ -0,0 +1,27 @@
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    app_name: str = "AI Starter Kit"
+    debug: bool = False
+    
+    # Database
+    database_url: str = "postgresql+asyncpg://postgres:postgres@localhost:5432/app"
+    
+    # Redis
+    redis_url: str = "redis://localhost:6379"
+    
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8000
+    
+    
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

package/templates/python-backend/src/features/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-backend/src/features/health/__init__.py

@@ -0,0 +1,3 @@
+from .router import router
+
+__all__ = ["router"]

package/templates/python-backend/src/features/health/router.py

@@ -0,0 +1,13 @@
+from fastapi import APIRouter
+from .schemas import HealthResponse
+import pendulum
+
+router = APIRouter(prefix="/health", tags=["Health"])
+
+
+@router.get("", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    return HealthResponse(
+        status="healthy",
+        timestamp=pendulum.now("UTC").to_iso8601_string(),
+    )

package/templates/python-backend/src/features/health/schemas.py

@@ -0,0 +1,6 @@
+import msgspec
+
+
+class HealthResponse(msgspec.Struct):
+    status: str
+    timestamp: str

package/templates/python-backend/src/lib/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-backend/src/lib/cache.py

@@ -0,0 +1,38 @@
+from cachetools import TTLCache
+from functools import wraps
+from typing import TypeVar, Callable, Any
+import asyncio
+
+T = TypeVar("T")
+
+_cache: TTLCache[str, Any] = TTLCache(maxsize=1000, ttl=300)
+
+
+def cached(ttl: int = 300, maxsize: int = 128) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Simple in-memory cache decorator with TTL support."""
+    cache: TTLCache[str, Any] = TTLCache(maxsize=maxsize, ttl=ttl)
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            key = f"{func.__name__}:{args}:{kwargs}"
+            if key in cache:
+                return cache[key]
+            result = await func(*args, **kwargs)
+            cache[key] = result
+            return result
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            key = f"{func.__name__}:{args}:{kwargs}"
+            if key in cache:
+                return cache[key]
+            result = func(*args, **kwargs)
+            cache[key] = result
+            return result
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper  # type: ignore
+
+    return decorator

package/templates/python-backend/src/lib/database.py

@@ -0,0 +1,31 @@
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from src.config import get_settings
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+settings = get_settings()
+engine = create_async_engine(settings.database_url, echo=settings.debug)
+async_session_maker = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def init_db() -> None:
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+@asynccontextmanager
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise

package/templates/python-backend/src/lib/logging.py

@@ -0,0 +1,25 @@
+import structlog
+from src.config import get_settings
+
+settings = get_settings()
+
+
+def configure_logging() -> None:
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.dev.set_exc_info,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.dev.ConsoleRenderer() if settings.debug else structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(10 if settings.debug else 20),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str = __name__) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)

package/templates/python-backend/src/main.py

@@ -0,0 +1,38 @@
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+from fastapi import FastAPI
+from fastapi.responses import ORJSONResponse
+
+from src.config import get_settings
+from src.lib.logging import configure_logging, get_logger
+from src.features import health
+
+
+settings = get_settings()
+configure_logging()
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    logger.info("Starting application", app_name=settings.app_name)
+    yield
+    logger.info("Shutting down application")
+
+
+app = FastAPI(
+    title=settings.app_name,
+    description="Fast Python backend starter kit with high-performance packages",
+    version="1.0.0",
+    default_response_class=ORJSONResponse,
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.include_router(health.router)
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    return {"message": "Welcome to Python Starter Kit"}

package/templates/python-backend/tests/__init__.py

@@ -0,0 +1 @@
+

package/templates/python-backend/tests/test_health.py

@@ -0,0 +1,26 @@
+import pytest
+from httpx import AsyncClient, ASGITransport
+from src.main import app
+
+
+@pytest.fixture
+async def client() -> AsyncClient:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+
+
+@pytest.mark.asyncio
+async def test_health_check(client: AsyncClient) -> None:
+    response = await client.get("/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "healthy"
+    assert "timestamp" in data
+
+
+@pytest.mark.asyncio
+async def test_root(client: AsyncClient) -> None:
+    response = await client.get("/")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Welcome to Python Starter Kit"}