Feature/python api

[ctsilva]

feat: add declarative Python API and runtime

Overview

This PR introduces a declarative Python API for Autark, following the Altair/Vega-Lite design pattern. It enables users to create urban visual analytics applications using high-level Python code that generates JSON specifications executed by a TypeScript runtime.

Core Components

Python API (python/autark/ - ~2k lines of code)

• Declarative builders for data sources, transforms, views, and interactions
• Jupyter integration via anywidget
• Zero runtime dependencies in Python

Runtime System (autk-runtime/src/ - ~2k lines of code)

• TypeScript runtime that executes declarative specifications
• Data loader supporting OSM, GeoJSON, CSV, JSON, and GeoTIFF
• Transform executor and view renderer

Schema (schema/autark-spec-v0.1.json)

• Formal JSON Schema for validation
• TypeScript type definitions

Key Features

• Declarative approach - describe what, not how
• Jupyter-native - renders as interactive widgets in notebooks
• OSMnx compatible - tested with street network analysis
• JSON/GeoTIFF support - new data sources with geometry support

Example Usage

import autark as ak

spec = ak.Spec(
    data=[ak.OSM("manhattan", ["buildings", "roads"])],
    views=[ak.Map(layers=[...]), ak.Histogram(...)],
    links=[ak.Link(source="map", target="histogram", action="filter")]
)
# Renders automatically in Jupyter