kardocore 0.2.3

Modern Python CMS Framework - Fast, Typed, Secure, Modular

KardoCore

Modern Python Framework for CMS, Headless CMS, APIs and Enterprise Applications

---

🌟 Overview

KardoCore is a hybrid, modular, and AI-ready Python framework designed for building modern web applications, CMS platforms, headless CMS, REST APIs, and enterprise solutions.

Key Features

• ⚡ Asynchronous ASGI Architecture - Built for high performance
• 🎨 Native Template Engine (KardoTheme) - Natural syntax with # prefix
• 📦 Package Manager - Install and manage themes easily
• 🔒 Built-in Validation System - No external dependencies
• 🤖 AI-Ready (KardoAI) - Native integration for AI features
• 🧩 Extreme Modularity - Use only what you need
• 🌍 Multi-language Support - i18n ready

---

🎯 Installation Modes

KardoCore offers 4 flexible installation modes to fit your needs:

1. Core Only - Headless CMS / REST API

Perfect for: API backends, microservices, headless CMS

┌─────────────┐
│  KardoCore  │  ← Core framework only
└─────────────┘

Use cases:

• REST API development
• Headless CMS backend
• Microservices
• GraphQL servers
• API-first applications

Installation:

pip install kardocore

---

2. Core + KardoAdmin - CMS with Admin Panel

Perfect for: Content management with admin interface

┌─────────────┐
│  KardoCore  │
├─────────────┤
│ KardoAdmin  │  ← Admin panel
└─────────────┘

Use cases:

• Content management systems
• Admin dashboards
• User management
• Data administration
• Backend management

Installation:

pip install kardocore[admin]

---

3. Core + Admin + Theme - Full CMS (Complete Solution)

Perfect for: Full-featured websites and CMS platforms

┌─────────────┐
│  KardoCore  │
├─────────────┤
│ KardoAdmin  │
├─────────────┤
│ KardoTheme  │  ← Frontend templates
└─────────────┘

Use cases:

• Complete CMS platforms
• Corporate websites
• E-commerce sites
• Blogs and portfolios
• Multi-page applications

Installation:

pip install kardocore[full]

---

4. KardoTheme Only - Frontend Only

Perfect for: Static sites, frontend-only projects

┌─────────────┐
│ KardoTheme  │  ← Template engine only
└─────────────┘

Use cases:

• Static site generation
• Frontend templates
• Email templates
• PDF generation
• Report generation

Installation:

pip install kardotheme

---

🚀 Quick Start

Installation Options

From PyPI (Recommended):

# Core only
pip install kardocore

# With admin panel
pip install kardocore[admin]

# Full CMS (Core + Admin + Theme)
pip install kardocore[full]

# Theme engine only
pip install kardotheme

From GitHub:

# Stable version (Python 3.11+)
pip install git+https://github.com/webcien/Kardo.git@v0.0.9

# Development version (Python 3.14+)
pip install git+https://github.com/webcien/Kardo.git@main

With npm (for frontend assets):

# Install KardoCSS
npm install @kardo/css

# Install KardoTheme compiler
npm install @kardo/theme-compiler

---

📋 Version Information

KardoCore is available in two versions to support different Python environments:

🎯 v0.0.9 (Stable) - RECOMMENDED FOR PRODUCTION

• Python: >= 3.11
• Status: Stable and production-ready
• Branch: v0.0.9
• Compatible with: Python 3.11, 3.12, 3.13, 3.14+

🚀 v0.1.0-alpha (Development)

• Python: >= 3.14
• Status: Active development
• Branch: main
• Features: Uses Python 3.14 modern features (PEP 649/749)

📖 See detailed version comparison →

---

💡 Usage Examples

Mode 1: Core Only (Headless API)

from kardocore import KardoApp

app = KardoApp()

@app.route("/api/posts")
async def get_posts(request):
    return {
        "posts": [
            {"id": 1, "title": "First Post"},
            {"id": 2, "title": "Second Post"}
        ]
    }

if __name__ == "__main__":
    app.run()

---

Mode 2: Core + Admin

from kardocore import KardoApp
from kardocore.admin import KardoAdmin

app = KardoApp()
admin = KardoAdmin(app)

# Register models for admin
@admin.register
class Post:
    title: str
    content: str
    published: bool

if __name__ == "__main__":
    app.run()

Access admin at: http://localhost:8000/admin

---

Mode 3: Full CMS (Core + Admin + Theme)

from kardocore import KardoApp
from kardocore.admin import KardoAdmin
from kardocore.theme import KardoTheme

app = KardoApp()
admin = KardoAdmin(app)
theme = KardoTheme(template_dir="templates")

@app.route("/")
async def index(request):
    context = {
        "title": "Welcome",
        "posts": Post.objects.all()
    }
    return theme.render("index.html", context)

if __name__ == "__main__":
    app.run()

---

Mode 4: Theme Only (Frontend)

from kardotheme import KardoTheme

theme = KardoTheme(template_dir="templates")

# Render template
html = theme.render("page.html", {
    "title": "My Page",
    "content": "Hello World"
})

# Save to file
with open("output.html", "w") as f:
    f.write(html)

---

🤖 KardoAI - AI Integration

KardoAI is the native AI integration layer for KardoCore, providing seamless AI capabilities across all modes.

Key Features

• 🧠 Content Generation - AI-powered content creation
• 🔍 Smart Search - Semantic search with embeddings
• 💬 Chatbots - Integrated conversational AI
• 🎨 Image Generation - AI image creation and editing
• 📝 Auto-completion - Smart text suggestions
• 🌐 Translation - Multi-language AI translation
• 📊 Analytics - AI-powered insights

How KardoAI Works

┌──────────────────────────────────────┐
│          Your Application            │
│                                      │
│  ┌────────────────────────────────┐ │
│  │         KardoCore              │ │
│  │  ┌──────────────────────────┐  │ │
│  │  │       KardoAI            │  │ │
│  │  │  ┌────────────────────┐  │  │ │
│  │  │  │  AI Providers      │  │  │ │
│  │  │  │  - OpenAI          │  │  │ │
│  │  │  │  - Anthropic       │  │  │ │
│  │  │  │  - Google AI       │  │  │ │
│  │  │  │  - Local Models    │  │  │ │
│  │  │  └────────────────────┘  │  │ │
│  │  └──────────────────────────┘  │ │
│  └────────────────────────────────┘ │
└──────────────────────────────────────┘

KardoAI Usage Example

from kardocore import KardoApp
from kardocore.ai import KardoAI

app = KardoApp()
ai = KardoAI(app, provider="openai")

@app.route("/api/generate")
async def generate_content(request):
    prompt = request.json.get("prompt")
    
    # Generate content with AI
    content = await ai.generate(
        prompt=prompt,
        max_tokens=500,
        temperature=0.7
    )
    
    return {"content": content}

@app.route("/api/search")
async def semantic_search(request):
    query = request.json.get("query")
    
    # Semantic search with embeddings
    results = await ai.search(
        query=query,
        collection="posts",
        limit=10
    )
    
    return {"results": results}

@app.route("/api/chat")
async def chat(request):
    message = request.json.get("message")
    
    # Conversational AI
    response = await ai.chat(
        message=message,
        context=request.session.get("chat_history", [])
    )
    
    return {"response": response}

KardoAI Configuration

# config.py
KARDOAI_CONFIG = {
    "provider": "openai",  # openai, anthropic, google, local
    "api_key": "your-api-key",
    "model": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 1000,
    
    # Features
    "content_generation": True,
    "semantic_search": True,
    "chatbot": True,
    "image_generation": True,
    "translation": True,
    
    # Embeddings
    "embeddings_model": "text-embedding-3-small",
    "vector_db": "chromadb",  # chromadb, pinecone, weaviate
    
    # Safety
    "content_filter": True,
    "rate_limiting": True,
    "cost_tracking": True
}

KardoAI in Admin Panel

When using Mode 2 or Mode 3, KardoAI integrates directly into the admin panel:

• ✍️ Content Editor: AI writing assistant
• 🖼️ Image Library: AI image generation
• 🔍 Search Bar: Semantic search
• 💬 Help Chat: AI-powered support
• 📊 Analytics: AI insights and recommendations

---

🎨 Template Engine (KardoTheme)

KardoCore includes a powerful native template engine with natural syntax.

Template Example

templates/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>{title}</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kardo/css@latest/dist/kardo.min.css">
</head>
<body>
    <h1>{title}</h1>
    
    #if items
        <ul>
        #for item in items
            <li>{item.name} - ${item.price}</li>
        #end
        </ul>
    #else
        <p>No items available</p>
    #end
    
    #include "partials/footer.html"
</body>
</html>

Template Syntax

Syntax	Description	Example
{variable}	Variable interpolation	{user.name}
#if condition	Conditional	#if user.is_admin
#else	Else clause	#else
#end	End block	#end
#for item in items	Loop	#for post in posts
#include "file"	Include template	#include "header.html"
{# comment #}	Comment	{# TODO: fix this #}

---

📦 Package Manager

Install and manage themes from the official registry.

CLI Commands

# Install a theme
kardo theme install wellness-clinic

# List installed themes
kardo theme list

# Search themes
kardo theme search health

# View theme info
kardo theme info wellness-clinic

# Uninstall theme
kardo theme uninstall wellness-clinic

---

🏗️ Project Structure

my_project/
├── app.py              # Main application
├── config.py           # Configuration
├── models/             # Data models
│   ├── __init__.py
│   ├── post.py
│   └── user.py
├── routes/             # Route handlers
│   ├── __init__.py
│   ├── api.py
│   └── web.py
├── templates/          # KardoTheme templates
│   ├── layout.html
│   ├── index.html
│   └── partials/
│       ├── header.html
│       └── footer.html
├── static/             # Static files
│   ├── css/
│   ├── js/
│   └── images/
├── admin/              # Admin customization
│   └── config.py
├── requirements.txt
└── package.json        # For npm dependencies

---

📚 Documentation

• Installation Guide - Detailed installation for all modes
• Quick Start Guide - Get started in 5 minutes
• Version Info - Compare v0.0.9 and v0.1.0
• Changelog - Version history
• Contributing - How to contribute
• KardoAI Guide - AI integration documentation

Language-Specific Documentation

• 🇺🇸 English: README.md (this file)
• 🇪🇸 Español: README.es.md

---

🌐 Ecosystem

KardoCore is part of the Kardo Ecosystem:

KardoCSS

Mobile-first CSS framework with utilities and components

• 67KB full / 50KB minified
• 20+ components
• 100+ utilities
• Touch-optimized

Installation:

npm install @kardo/css
# or
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kardo/css@latest/dist/kardo.min.css">

KardoTemplates

Professional template collection for KardoCore

• 60 templates (50 frontend + 10 backend)
• 15 frontend categories
• 2 backend categories
• Mobile-first responsive

Installation:

kardo theme install wellness-clinic

---

🎯 Use Cases by Mode

Mode 1: Core Only

• ✅ REST API backends
• ✅ Headless CMS
• ✅ Microservices
• ✅ GraphQL servers
• ✅ API gateways

Mode 2: Core + Admin

• ✅ Content management
• ✅ User administration
• ✅ Data dashboards
• ✅ Backend systems
• ✅ Internal tools

Mode 3: Full CMS

• ✅ Corporate websites
• ✅ E-commerce platforms
• ✅ Blogs and magazines
• ✅ Portfolios
• ✅ Community sites

Mode 4: Theme Only

• ✅ Static site generation
• ✅ Email templates
• ✅ PDF reports
• ✅ Documentation sites
• ✅ Landing pages

---

🔧 Requirements

For v0.0.9 (Stable)

• Python >= 3.11
• uvicorn >= 0.30.0

For v0.1.0-alpha (Development)

• Python >= 3.14
• uvicorn >= 0.30.0

Optional Dependencies

• Admin Panel: pip install kardocore[admin]
• Full CMS: pip install kardocore[full]
• AI Features: pip install kardocore[ai]
• All Features: pip install kardocore[all]

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/webcien/Kardo.git
cd Kardo

# For stable version
git checkout v0.0.9

# For development version
git checkout main

# Install in development mode with all features
pip install -e ".[all]"

# Run tests
pytest

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation
• Discord: Join our community

---

🗺️ Roadmap

v0.0.9 (Current - Stable)

• ✅ Python 3.11+ compatibility
• ✅ Core features complete
• ✅ 4 installation modes
• 🔄 Bug fixes and improvements
• 🔄 Documentation

v0.1.0-alpha (Current - Development)

• ✅ Python 3.14+ optimizations
• 🔄 KardoAI integration
• 🔄 Experimental features
• 📅 PyPI publication
• 📅 npm packages

v1.0.0 (Future)

• 📅 Stable unified version
• 📅 Complete KardoAI features
• 📅 Multi-database support
• 📅 GraphQL support
• 📅 WebSocket support
• 📅 Complete documentation
• 📅 Production-ready

---

⭐ Star History

If you find KardoCore useful, please consider giving it a star on GitHub!

---

Made with ❤️ by the Kardo Team

Website • Documentation • Blog • Twitter