kardocore

Name	kardocore JSON
Version	0.2.3 JSON
	download
home_page	https://github.com/webcien/Kardo
Summary	Modern Python CMS Framework - Fast, Typed, Secure, Modular
upload_time	2025-10-26 00:05:32
maintainer	None
docs_url	None
author	WebCien
requires_python	>=3.11
license	MIT
keywords	cms framework web async database authentication theme template modern typed fast secure modular
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # KardoCore

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

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-0.0.9-orange.svg)](https://github.com/webcien/Kardo/releases/tag/v0.0.9)
[![PyPI](https://img.shields.io/badge/PyPI-Coming%20Soon-orange.svg)](https://pypi.org/)
[![npm](https://img.shields.io/badge/npm-Coming%20Soon-red.svg)](https://www.npmjs.com/)

---

## 🌟 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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
pip install kardotheme
```

---

## 🚀 Quick Start

### Installation Options

**From PyPI (Recommended):**
```bash
# 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:**
```bash
# 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):**
```bash
# 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 →](VERSION_INFO.md)**

---

## 💡 Usage Examples

### Mode 1: Core Only (Headless API)

```python
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

```python
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)

```python
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)

```python
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

```python
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

```python
# 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:**
```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

```bash
# 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](HOW-TO-INSTALL.md)** - Detailed installation for all modes
- **[Quick Start Guide](QUICK-START.md)** - Get started in 5 minutes
- **[Version Info](VERSION_INFO.md)** - Compare v0.0.9 and v0.1.0
- **[Changelog](CHANGELOG.md)** - Version history
- **[Contributing](CONTRIBUTING.md)** - How to contribute
- **[KardoAI Guide](docs/KARDOAI.md)** - AI integration documentation

### Language-Specific Documentation

- 🇺🇸 **English**: README.md (this file)
- 🇪🇸 **Español**: [README.es.md](README.es.md)

---

## 🌐 Ecosystem

KardoCore is part of the **Kardo Ecosystem**:

### [KardoCSS](https://github.com/webcien/KardoCSS)
Mobile-first CSS framework with utilities and components
- 67KB full / 50KB minified
- 20+ components
- 100+ utilities
- Touch-optimized

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

### [KardoTemplates](https://github.com/webcien/KardoTemplates)
Professional template collection for KardoCore
- 60 templates (50 frontend + 10 backend)
- 15 frontend categories
- 2 backend categories
- Mobile-first responsive

**Installation:**
```bash
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](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# 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](LICENSE) file for details.

---

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/webcien/Kardo/issues)
- **Discussions**: [GitHub Discussions](https://github.com/webcien/Kardo/discussions)
- **Documentation**: [Full Documentation](https://kardo.dev/docs)
- **Discord**: [Join our community](https://discord.gg/kardo)

---

## 🗺️ 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!

[![Star History Chart](https://api.star-history.com/svg?repos=webcien/Kardo&type=Date)](https://star-history.com/#webcien/Kardo&Date)

---

**Made with ❤️ by the Kardo Team**

[Website](https://kardo.dev) • [Documentation](https://kardo.dev/docs) • [Blog](https://kardo.dev/blog) • [Twitter](https://twitter.com/kardoframework)


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/webcien/Kardo",
    "name": "kardocore",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "cms, framework, web, async, database, authentication, theme, template, modern, typed, fast, secure, modular",
    "author": "WebCien",
    "author_email": "WebCien <contact@webcien.com>",
    "download_url": "https://files.pythonhosted.org/packages/c6/36/369e473b50c5f5bf96dc755c10ef85f97086182fea8fd303496f7528579b/kardocore-0.2.3.tar.gz",
    "platform": null,
    "description": "# KardoCore\n\n**Modern Python Framework for CMS, Headless CMS, APIs and Enterprise Applications**\n\n[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/Version-0.0.9-orange.svg)](https://github.com/webcien/Kardo/releases/tag/v0.0.9)\n[![PyPI](https://img.shields.io/badge/PyPI-Coming%20Soon-orange.svg)](https://pypi.org/)\n[![npm](https://img.shields.io/badge/npm-Coming%20Soon-red.svg)](https://www.npmjs.com/)\n\n---\n\n## \ud83c\udf1f Overview\n\n**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.\n\n### Key Features\n\n- \u26a1 **Asynchronous ASGI Architecture** - Built for high performance\n- \ud83c\udfa8 **Native Template Engine (KardoTheme)** - Natural syntax with `#` prefix\n- \ud83d\udce6 **Package Manager** - Install and manage themes easily\n- \ud83d\udd12 **Built-in Validation System** - No external dependencies\n- \ud83e\udd16 **AI-Ready (KardoAI)** - Native integration for AI features\n- \ud83e\udde9 **Extreme Modularity** - Use only what you need\n- \ud83c\udf0d **Multi-language Support** - i18n ready\n\n---\n\n## \ud83c\udfaf Installation Modes\n\nKardoCore offers **4 flexible installation modes** to fit your needs:\n\n### 1. **Core Only** - Headless CMS / REST API\n**Perfect for:** API backends, microservices, headless CMS\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  KardoCore  \u2502  \u2190 Core framework only\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Use cases:**\n- REST API development\n- Headless CMS backend\n- Microservices\n- GraphQL servers\n- API-first applications\n\n**Installation:**\n```bash\npip install kardocore\n```\n\n---\n\n### 2. **Core + KardoAdmin** - CMS with Admin Panel\n**Perfect for:** Content management with admin interface\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  KardoCore  \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 KardoAdmin  \u2502  \u2190 Admin panel\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Use cases:**\n- Content management systems\n- Admin dashboards\n- User management\n- Data administration\n- Backend management\n\n**Installation:**\n```bash\npip install kardocore[admin]\n```\n\n---\n\n### 3. **Core + Admin + Theme** - Full CMS (Complete Solution)\n**Perfect for:** Full-featured websites and CMS platforms\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  KardoCore  \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 KardoAdmin  \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 KardoTheme  \u2502  \u2190 Frontend templates\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Use cases:**\n- Complete CMS platforms\n- Corporate websites\n- E-commerce sites\n- Blogs and portfolios\n- Multi-page applications\n\n**Installation:**\n```bash\npip install kardocore[full]\n```\n\n---\n\n### 4. **KardoTheme Only** - Frontend Only\n**Perfect for:** Static sites, frontend-only projects\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 KardoTheme  \u2502  \u2190 Template engine only\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Use cases:**\n- Static site generation\n- Frontend templates\n- Email templates\n- PDF generation\n- Report generation\n\n**Installation:**\n```bash\npip install kardotheme\n```\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation Options\n\n**From PyPI (Recommended):**\n```bash\n# Core only\npip install kardocore\n\n# With admin panel\npip install kardocore[admin]\n\n# Full CMS (Core + Admin + Theme)\npip install kardocore[full]\n\n# Theme engine only\npip install kardotheme\n```\n\n**From GitHub:**\n```bash\n# Stable version (Python 3.11+)\npip install git+https://github.com/webcien/Kardo.git@v0.0.9\n\n# Development version (Python 3.14+)\npip install git+https://github.com/webcien/Kardo.git@main\n```\n\n**With npm (for frontend assets):**\n```bash\n# Install KardoCSS\nnpm install @kardo/css\n\n# Install KardoTheme compiler\nnpm install @kardo/theme-compiler\n```\n\n---\n\n## \ud83d\udccb Version Information\n\nKardoCore is available in **two versions** to support different Python environments:\n\n### \ud83c\udfaf v0.0.9 (Stable) - **RECOMMENDED FOR PRODUCTION**\n- **Python**: >= 3.11\n- **Status**: Stable and production-ready\n- **Branch**: `v0.0.9`\n- **Compatible with**: Python 3.11, 3.12, 3.13, 3.14+\n\n### \ud83d\ude80 v0.1.0-alpha (Development)\n- **Python**: >= 3.14\n- **Status**: Active development\n- **Branch**: `main`\n- **Features**: Uses Python 3.14 modern features (PEP 649/749)\n\n**\ud83d\udcd6 [See detailed version comparison \u2192](VERSION_INFO.md)**\n\n---\n\n## \ud83d\udca1 Usage Examples\n\n### Mode 1: Core Only (Headless API)\n\n```python\nfrom kardocore import KardoApp\n\napp = KardoApp()\n\n@app.route(\"/api/posts\")\nasync def get_posts(request):\n    return {\n        \"posts\": [\n            {\"id\": 1, \"title\": \"First Post\"},\n            {\"id\": 2, \"title\": \"Second Post\"}\n        ]\n    }\n\nif __name__ == \"__main__\":\n    app.run()\n```\n\n---\n\n### Mode 2: Core + Admin\n\n```python\nfrom kardocore import KardoApp\nfrom kardocore.admin import KardoAdmin\n\napp = KardoApp()\nadmin = KardoAdmin(app)\n\n# Register models for admin\n@admin.register\nclass Post:\n    title: str\n    content: str\n    published: bool\n\nif __name__ == \"__main__\":\n    app.run()\n```\n\nAccess admin at: `http://localhost:8000/admin`\n\n---\n\n### Mode 3: Full CMS (Core + Admin + Theme)\n\n```python\nfrom kardocore import KardoApp\nfrom kardocore.admin import KardoAdmin\nfrom kardocore.theme import KardoTheme\n\napp = KardoApp()\nadmin = KardoAdmin(app)\ntheme = KardoTheme(template_dir=\"templates\")\n\n@app.route(\"/\")\nasync def index(request):\n    context = {\n        \"title\": \"Welcome\",\n        \"posts\": Post.objects.all()\n    }\n    return theme.render(\"index.html\", context)\n\nif __name__ == \"__main__\":\n    app.run()\n```\n\n---\n\n### Mode 4: Theme Only (Frontend)\n\n```python\nfrom kardotheme import KardoTheme\n\ntheme = KardoTheme(template_dir=\"templates\")\n\n# Render template\nhtml = theme.render(\"page.html\", {\n    \"title\": \"My Page\",\n    \"content\": \"Hello World\"\n})\n\n# Save to file\nwith open(\"output.html\", \"w\") as f:\n    f.write(html)\n```\n\n---\n\n## \ud83e\udd16 KardoAI - AI Integration\n\n**KardoAI** is the native AI integration layer for KardoCore, providing seamless AI capabilities across all modes.\n\n### Key Features\n\n- \ud83e\udde0 **Content Generation** - AI-powered content creation\n- \ud83d\udd0d **Smart Search** - Semantic search with embeddings\n- \ud83d\udcac **Chatbots** - Integrated conversational AI\n- \ud83c\udfa8 **Image Generation** - AI image creation and editing\n- \ud83d\udcdd **Auto-completion** - Smart text suggestions\n- \ud83c\udf10 **Translation** - Multi-language AI translation\n- \ud83d\udcca **Analytics** - AI-powered insights\n\n### How KardoAI Works\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502          Your Application            \u2502\n\u2502                                      \u2502\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502  \u2502         KardoCore              \u2502 \u2502\n\u2502  \u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u2502 \u2502\n\u2502  \u2502  \u2502       KardoAI            \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2502  AI Providers      \u2502  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2502  - OpenAI          \u2502  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2502  - Anthropic       \u2502  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2502  - Google AI       \u2502  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2502  - Local Models    \u2502  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502  \u2502 \u2502\n\u2502  \u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502 \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### KardoAI Usage Example\n\n```python\nfrom kardocore import KardoApp\nfrom kardocore.ai import KardoAI\n\napp = KardoApp()\nai = KardoAI(app, provider=\"openai\")\n\n@app.route(\"/api/generate\")\nasync def generate_content(request):\n    prompt = request.json.get(\"prompt\")\n    \n    # Generate content with AI\n    content = await ai.generate(\n        prompt=prompt,\n        max_tokens=500,\n        temperature=0.7\n    )\n    \n    return {\"content\": content}\n\n@app.route(\"/api/search\")\nasync def semantic_search(request):\n    query = request.json.get(\"query\")\n    \n    # Semantic search with embeddings\n    results = await ai.search(\n        query=query,\n        collection=\"posts\",\n        limit=10\n    )\n    \n    return {\"results\": results}\n\n@app.route(\"/api/chat\")\nasync def chat(request):\n    message = request.json.get(\"message\")\n    \n    # Conversational AI\n    response = await ai.chat(\n        message=message,\n        context=request.session.get(\"chat_history\", [])\n    )\n    \n    return {\"response\": response}\n```\n\n### KardoAI Configuration\n\n```python\n# config.py\nKARDOAI_CONFIG = {\n    \"provider\": \"openai\",  # openai, anthropic, google, local\n    \"api_key\": \"your-api-key\",\n    \"model\": \"gpt-4\",\n    \"temperature\": 0.7,\n    \"max_tokens\": 1000,\n    \n    # Features\n    \"content_generation\": True,\n    \"semantic_search\": True,\n    \"chatbot\": True,\n    \"image_generation\": True,\n    \"translation\": True,\n    \n    # Embeddings\n    \"embeddings_model\": \"text-embedding-3-small\",\n    \"vector_db\": \"chromadb\",  # chromadb, pinecone, weaviate\n    \n    # Safety\n    \"content_filter\": True,\n    \"rate_limiting\": True,\n    \"cost_tracking\": True\n}\n```\n\n### KardoAI in Admin Panel\n\nWhen using **Mode 2** or **Mode 3**, KardoAI integrates directly into the admin panel:\n\n- \u270d\ufe0f **Content Editor**: AI writing assistant\n- \ud83d\uddbc\ufe0f **Image Library**: AI image generation\n- \ud83d\udd0d **Search Bar**: Semantic search\n- \ud83d\udcac **Help Chat**: AI-powered support\n- \ud83d\udcca **Analytics**: AI insights and recommendations\n\n---\n\n## \ud83c\udfa8 Template Engine (KardoTheme)\n\nKardoCore includes a powerful native template engine with natural syntax.\n\n### Template Example\n\n**templates/index.html:**\n```html\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <title>{title}</title>\n    <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@kardo/css@latest/dist/kardo.min.css\">\n</head>\n<body>\n    <h1>{title}</h1>\n    \n    #if items\n        <ul>\n        #for item in items\n            <li>{item.name} - ${item.price}</li>\n        #end\n        </ul>\n    #else\n        <p>No items available</p>\n    #end\n    \n    #include \"partials/footer.html\"\n</body>\n</html>\n```\n\n### Template Syntax\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `{variable}` | Variable interpolation | `{user.name}` |\n| `#if condition` | Conditional | `#if user.is_admin` |\n| `#else` | Else clause | `#else` |\n| `#end` | End block | `#end` |\n| `#for item in items` | Loop | `#for post in posts` |\n| `#include \"file\"` | Include template | `#include \"header.html\"` |\n| `{# comment #}` | Comment | `{# TODO: fix this #}` |\n\n---\n\n## \ud83d\udce6 Package Manager\n\nInstall and manage themes from the official registry.\n\n### CLI Commands\n\n```bash\n# Install a theme\nkardo theme install wellness-clinic\n\n# List installed themes\nkardo theme list\n\n# Search themes\nkardo theme search health\n\n# View theme info\nkardo theme info wellness-clinic\n\n# Uninstall theme\nkardo theme uninstall wellness-clinic\n```\n\n---\n\n## \ud83c\udfd7\ufe0f Project Structure\n\n```\nmy_project/\n\u251c\u2500\u2500 app.py              # Main application\n\u251c\u2500\u2500 config.py           # Configuration\n\u251c\u2500\u2500 models/             # Data models\n\u2502   \u251c\u2500\u2500 __init__.py\n\u2502   \u251c\u2500\u2500 post.py\n\u2502   \u2514\u2500\u2500 user.py\n\u251c\u2500\u2500 routes/             # Route handlers\n\u2502   \u251c\u2500\u2500 __init__.py\n\u2502   \u251c\u2500\u2500 api.py\n\u2502   \u2514\u2500\u2500 web.py\n\u251c\u2500\u2500 templates/          # KardoTheme templates\n\u2502   \u251c\u2500\u2500 layout.html\n\u2502   \u251c\u2500\u2500 index.html\n\u2502   \u2514\u2500\u2500 partials/\n\u2502       \u251c\u2500\u2500 header.html\n\u2502       \u2514\u2500\u2500 footer.html\n\u251c\u2500\u2500 static/             # Static files\n\u2502   \u251c\u2500\u2500 css/\n\u2502   \u251c\u2500\u2500 js/\n\u2502   \u2514\u2500\u2500 images/\n\u251c\u2500\u2500 admin/              # Admin customization\n\u2502   \u2514\u2500\u2500 config.py\n\u251c\u2500\u2500 requirements.txt\n\u2514\u2500\u2500 package.json        # For npm dependencies\n```\n\n---\n\n## \ud83d\udcda Documentation\n\n- **[Installation Guide](HOW-TO-INSTALL.md)** - Detailed installation for all modes\n- **[Quick Start Guide](QUICK-START.md)** - Get started in 5 minutes\n- **[Version Info](VERSION_INFO.md)** - Compare v0.0.9 and v0.1.0\n- **[Changelog](CHANGELOG.md)** - Version history\n- **[Contributing](CONTRIBUTING.md)** - How to contribute\n- **[KardoAI Guide](docs/KARDOAI.md)** - AI integration documentation\n\n### Language-Specific Documentation\n\n- \ud83c\uddfa\ud83c\uddf8 **English**: README.md (this file)\n- \ud83c\uddea\ud83c\uddf8 **Espa\u00f1ol**: [README.es.md](README.es.md)\n\n---\n\n## \ud83c\udf10 Ecosystem\n\nKardoCore is part of the **Kardo Ecosystem**:\n\n### [KardoCSS](https://github.com/webcien/KardoCSS)\nMobile-first CSS framework with utilities and components\n- 67KB full / 50KB minified\n- 20+ components\n- 100+ utilities\n- Touch-optimized\n\n**Installation:**\n```bash\nnpm install @kardo/css\n# or\n<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@kardo/css@latest/dist/kardo.min.css\">\n```\n\n### [KardoTemplates](https://github.com/webcien/KardoTemplates)\nProfessional template collection for KardoCore\n- 60 templates (50 frontend + 10 backend)\n- 15 frontend categories\n- 2 backend categories\n- Mobile-first responsive\n\n**Installation:**\n```bash\nkardo theme install wellness-clinic\n```\n\n---\n\n## \ud83c\udfaf Use Cases by Mode\n\n### Mode 1: Core Only\n- \u2705 REST API backends\n- \u2705 Headless CMS\n- \u2705 Microservices\n- \u2705 GraphQL servers\n- \u2705 API gateways\n\n### Mode 2: Core + Admin\n- \u2705 Content management\n- \u2705 User administration\n- \u2705 Data dashboards\n- \u2705 Backend systems\n- \u2705 Internal tools\n\n### Mode 3: Full CMS\n- \u2705 Corporate websites\n- \u2705 E-commerce platforms\n- \u2705 Blogs and magazines\n- \u2705 Portfolios\n- \u2705 Community sites\n\n### Mode 4: Theme Only\n- \u2705 Static site generation\n- \u2705 Email templates\n- \u2705 PDF reports\n- \u2705 Documentation sites\n- \u2705 Landing pages\n\n---\n\n## \ud83d\udd27 Requirements\n\n### For v0.0.9 (Stable)\n- Python >= 3.11\n- uvicorn >= 0.30.0\n\n### For v0.1.0-alpha (Development)\n- Python >= 3.14\n- uvicorn >= 0.30.0\n\n### Optional Dependencies\n- **Admin Panel**: `pip install kardocore[admin]`\n- **Full CMS**: `pip install kardocore[full]`\n- **AI Features**: `pip install kardocore[ai]`\n- **All Features**: `pip install kardocore[all]`\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/webcien/Kardo.git\ncd Kardo\n\n# For stable version\ngit checkout v0.0.9\n\n# For development version\ngit checkout main\n\n# Install in development mode with all features\npip install -e \".[all]\"\n\n# Run tests\npytest\n```\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/webcien/Kardo/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/webcien/Kardo/discussions)\n- **Documentation**: [Full Documentation](https://kardo.dev/docs)\n- **Discord**: [Join our community](https://discord.gg/kardo)\n\n---\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n### v0.0.9 (Current - Stable)\n- \u2705 Python 3.11+ compatibility\n- \u2705 Core features complete\n- \u2705 4 installation modes\n- \ud83d\udd04 Bug fixes and improvements\n- \ud83d\udd04 Documentation\n\n### v0.1.0-alpha (Current - Development)\n- \u2705 Python 3.14+ optimizations\n- \ud83d\udd04 KardoAI integration\n- \ud83d\udd04 Experimental features\n- \ud83d\udcc5 PyPI publication\n- \ud83d\udcc5 npm packages\n\n### v1.0.0 (Future)\n- \ud83d\udcc5 Stable unified version\n- \ud83d\udcc5 Complete KardoAI features\n- \ud83d\udcc5 Multi-database support\n- \ud83d\udcc5 GraphQL support\n- \ud83d\udcc5 WebSocket support\n- \ud83d\udcc5 Complete documentation\n- \ud83d\udcc5 Production-ready\n\n---\n\n## \u2b50 Star History\n\nIf you find KardoCore useful, please consider giving it a star on GitHub!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=webcien/Kardo&type=Date)](https://star-history.com/#webcien/Kardo&Date)\n\n---\n\n**Made with \u2764\ufe0f by the Kardo Team**\n\n[Website](https://kardo.dev) \u2022 [Documentation](https://kardo.dev/docs) \u2022 [Blog](https://kardo.dev/blog) \u2022 [Twitter](https://twitter.com/kardoframework)\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Modern Python CMS Framework - Fast, Typed, Secure, Modular",
    "version": "0.2.3",
    "project_urls": {
        "Homepage": "https://github.com/webcien/Kardo",
        "Repository": "https://github.com/webcien/Kardo"
    },
    "split_keywords": [
        "cms",
        " framework",
        " web",
        " async",
        " database",
        " authentication",
        " theme",
        " template",
        " modern",
        " typed",
        " fast",
        " secure",
        " modular"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "20720903294c24b83c279ed8ff8cfda2717b22e8f17fea056701116403e186a5",
                "md5": "12a96b558d5afa969d5552e529f28ff8",
                "sha256": "6e5d06b8f4c7b20d77d909a83cc7ab865351bd12fd2885ca64083cf8b9088f20"
            },
            "downloads": -1,
            "filename": "kardocore-0.2.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "12a96b558d5afa969d5552e529f28ff8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 57416,
            "upload_time": "2025-10-26T00:05:30",
            "upload_time_iso_8601": "2025-10-26T00:05:30.399536Z",
            "url": "https://files.pythonhosted.org/packages/20/72/0903294c24b83c279ed8ff8cfda2717b22e8f17fea056701116403e186a5/kardocore-0.2.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c636369e473b50c5f5bf96dc755c10ef85f97086182fea8fd303496f7528579b",
                "md5": "6ff0979e521d138487599a66990f6978",
                "sha256": "ef4d4c36d31158b4eb0cf84927110127de6b3ade2b0ccfaac5edfb35bb6b9599"
            },
            "downloads": -1,
            "filename": "kardocore-0.2.3.tar.gz",
            "has_sig": false,
            "md5_digest": "6ff0979e521d138487599a66990f6978",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 86257,
            "upload_time": "2025-10-26T00:05:32",
            "upload_time_iso_8601": "2025-10-26T00:05:32.498990Z",
            "url": "https://files.pythonhosted.org/packages/c6/36/369e473b50c5f5bf96dc755c10ef85f97086182fea8fd303496f7528579b/kardocore-0.2.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-26 00:05:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "webcien",
    "github_project": "Kardo",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "kardocore"
}