telescope-cortex 0.0.1a7

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

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

🔧 Modules

📖 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: help@jointelescope.com
• Documentation: docs.jointelescope.com
• Pull Requests: Contribute