Welcome to Cortex, a lightweight, modular analytics platform designed to power customer-facing analytics applications.

What is Cortex?

Cortex is a comprehensive analytics engine built in Python that provides a unified semantic layer for defining business data models, a dynamic query engine that integrates with heterogeneous data sources, and a robust user management system—all accessible via a FastAPI-powered REST API.

Core Philosophy

Cortex was built with the following principles in mind:

• Semantic Abstraction: Business users should work with meaningful metrics without needing SQL knowledge
• Multi-Source Integration: Unified querying across different database types and sources
• Developer-Friendly: Clean APIs and extensive type safety for rapid development
• Extensible Architecture: Easy to add new database connectors and query capabilities
• AI-Ready: Designed with AI agent integration in mind for natural language querying

Key Features

Semantic Layer

• Define and manage data models in JSON with measures, dimensions, filters, and ordering
• Dynamic schema generation and validation
• Advanced output formatting with IN_QUERY and POST_QUERY transformation modes
• Semantic ordering with intelligent default sorting rules
• Versioning and audit trails for governance

Query Engine

• Translates semantic definitions into optimized queries across multiple data sources
• Supports PostgreSQL, MySQL, BigQuery, SQLite, Oracle, Snowflake, and Redshift
• Real-time output formatting during query execution and post-processing
• Integration with caching for enhanced performance

Multi-Tenant Architecture

• Hierarchical organization with workspaces, environments, and consumer groups
• Proper data isolation and environment-level configurations
• Support for multiple organizations with shared infrastructure

API-First Design

• All functionality exposed via FastAPI-based REST endpoints
• Clear separation of admin and end-user API flows
• Auto-generated OpenAPI documentation with Scalar FastAPI
• Comprehensive request/response validation with Pydantic

Studio Interface

• Built with Vue.js and Nuxt.js for modern administrative workflows
• Visual interface for configuring workspaces, data sources, and metrics
• Interactive metric builder with real-time preview capabilities
• Dashboard creation with drag-and-drop functionality
• Designed for administrators and data teams to configure analytics foundations

For Developers: Studio serves as a reference implementation. Developers are encouraged to build custom UIs tailored to their specific use cases. Learn more about Studio patterns and building custom interfaces.

Type Safety & Validation

• Comprehensive Pydantic validation throughout the system
• Runtime type safety and automatic API documentation
• Robust error handling with custom exception hierarchy
• IDE support with extensive type hints

Use Cases

Customer-Facing Analytics Platforms

Build white-labeled analytics dashboards for your customers, providing business users with self-service analytics without exposing underlying database complexity.

Enterprise Data Democratization

Enable business users to access and analyze data through semantic models, reducing dependency on data teams while maintaining proper governance and security.

Multi-Source Data Integration

Unify data from multiple sources into a single semantic layer, providing consistent business definitions and metrics across different systems and teams.

AI-Powered Analytics

Foundation for natural language querying and AI-driven insights. The structured semantic models enable AI agents to understand business context and generate intelligent analytics.

SaaS Analytics Platforms

Perfect for building analytics platforms serving multiple customers with proper data isolation and tenant-specific configurations.

Architecture Overview

Cortex follows a layered architecture that ensures modularity, maintainability, and independent evolution of core components:

Layered architecture showing client applications, API layer, business logic, data access, and storage components

Technology Stack

Getting Started

Ready to dive in? Head over to the Installation Guide to set up your first Cortex instance, or explore the Architecture Overview to understand the system design in detail.

Disclaimer

Cortex may not be the right fit for your use case. Please consider the following limitations:

When NOT to use Cortex

1. Access Control & Authorization: Currently all queries run unauthenticated. We are working on bringing in authorization support soon.
2. Large Query Results: If your average query returns more than 100k records, Cortex might be slow. We are currently working on performance optimizations to achieve almost sub-second latencies, but at the moment it's recommended to use other BI tools for large datasets.
3. Non-Python Codebases: Currently Cortex only works with Python codebases. We have plans to support other languages like JavaScript, Go, etc., but this is not available yet.

Alternative Recommendations

If Cortex is not the right fit for you, we recommend these alternatives:

1. Cube.dev - Open-source analytics API platform
2. Metabase - Open-source business intelligence tool
3. LightDash - Open-source metrics layer

Community & Support

Cortex is an open-source project. Join our community:

• GitHub: https://github.com/TelescopeAI/cortex
• Issues: Report bugs and request features
• Discussions: Share ideas and ask questions

Contributing

We welcome contributions! Whether it's bug fixes, new features, documentation improvements, or community support, every contribution helps make Cortex better.

Check out our Development Guide to get started with contributing to the project.