telescope-cortex 0.0.1a7

Minimal Headless BI for perfectionists on deadlines

 ______     ______     ______     ______   ______     __  __    
/\  ___\   /\  __ \   /\  == \   /\__  _\ /\  ___\   /\_\_\_\   
\ \ \____  \ \ \/\ \  \ \  __<   \/_/\ \/ \ \  __\   \/_/\_\/_  
 \ \_____\  \ \_____\  \ \_\ \_\    \ \_\  \ \_____\   /\_\/\_\ 
  \/_____/   \/_____/   \/_/ /_/     \/_/   \/_____/   \/_/\/_/ 
                                                                
                                                                                                         

The simplest semantic layer for building data driven applications.

Cortex provides a unified semantic layer that lets you define what matters once and ship analytics faster. Abstract away data complexity, monitor results in realtime, and take proactive actions all through a simple REST API built for modern developers and AI.

• 🎯 Semantic Layer: Define metrics, dimensions, and measures in JSON with support for output formatting, conditional logic, and parameter systems
• ⚡ Query Engine: Turn your metrics into optimized queries with built-in caching (Redis, in-memory)
• 🔌 Data Sources: PostgreSQL, MySQL, BigQuery, SQLite, and Spreadsheets (CSV/Google Sheets). Easy to add custom sources.
• 📊 Dashboards: Build dashboards using 10+ chart types. Easily extended to support custom visualizations.
• 📁 File Storage: Upload CSV files with automatic SQLite conversion, hash-based change detection, and cloud storage support (GCS)
• 👥 Multi Tenant: Hierarchical organization (Workspaces → Environments → Consumers) with context-aware query execution
• 🔐 API First: Comprehensive REST API with OpenAPI documentation

Quick Start

Installation

# Install with API support
pip install telescope-cortex[api]

# Start the server
python -m cortex

Access the API:

• API Server: http://localhost:9002
• Interactive Docs: http://localhost:9002/docs

For detailed installation instructions, see the Getting Started Guide.

Create Metric

import httpx

# Define a metric with output formatting
metric = {
    "name": "monthly_revenue",
    "description": "Total revenue aggregated by month",
    "table_name": "sales",
    "measures": [
        {
            "name": "revenue",
            "type": "sum",
            "query": "amount",
            "formatting": [{
                "name": "currency",
                "type": "format",
                "mode": "post_query",
                "format_string": "${:,.2f}"
            }]
        }
    ],
    "dimensions": [
        {
            "name": "month",
            "query": "sale_date",
            "type": "time"
        }
    ]
}

# Create the metric
response = httpx.post("http://localhost:9002/api/v1/metrics", json=metric)

# Execute the metric
result = httpx.post(
    f"http://localhost:9002/api/v1/metrics/{response.json()['id']}/execute",
    json={"parameters": {"start_date": "2024-01-01"}}
)

{
  "success": true,
  "data": [
    {
      "month": "2024-01-01",
      "revenue": "$12,500.50"
    },
    {
      "month": "2024-02-01",
      "revenue": "$14,230.75"
    }
  ],
  "metadata": {
    "metric_id": "8f3e5b12-9c1a-4d3b-8e2f-7a6c5b4d3e2f",
    "duration": 25.4,
    "row_count": 2,
    "query": "SELECT sale_date, SUM(amount) FROM sales WHERE sale_date >= '2024-01-01' GROUP BY 1",
    "parameters": {
      "start_date": "2024-01-01"
    }
  }
}

See the API Reference for complete API documentation.

Studio

Cortex includes a modern GUI for managing workspaces, data sources, metrics, and dashboards.

cd frontend/cortex
yarn install
yarn run dev

Documentation

📚 Core

Concepts	Description
Getting Started	Installation, configuration, and quick start tutorial
Architecture	System architecture
Multi Tenancy	Workspaces, environments, and consumer management
Development	Contributing guidelines and development setup

🔧 Modules

Module	Description
Core Modules	Overview of all core components
Semantic Layer	Metric definitions, measures, dimensions, and formatting
Query Engine	SQL generation, caching, and preaggregations
Data Sources	Database connectors and schema introspection
Dashboards	Visualization types and widget configuration
API Reference	REST API endpoints and usage examples

📖 Guides

• Database Migrations - Alembic migration management
• Spreadsheet Data Sources - CSV and Google Sheets configuration

Contributing

Contributions are welcome! Please see the Development Guide

License

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

Attribution

Cortex was inspired by Cube's Semantic Layer and Metabase. We built upon their work to create a lightweight analytics platform.

Support

For questions and support:

• Issues: GitHub Issues
• Email: [e-mail]
• Documentation: docs.jointelescope.com
• Pull Requests: Contribute