feat: Add time series end-to-end example and derived analytics

- Implemented `17_timeseries_end_to_end.py` to demonstrate a SQL-first time series workflow.
- Created a new TimeSeries type with multiple tags and numeric fields.
- Added functionality to generate synthetic telemetry data for sensors and bulk insert samples.
- Included raw window queries, hourly aggregations, and derived alert-style views.
- Updated README to document the new example and its capabilities.
- Introduced `run_examples_minimal.py` script to facilitate running multiple examples with minimal inputs.
- Enhanced `13_stackoverflow_hybrid_queries.py` with derived time-series analytics in phase 5.
- Updated `things-to-do.md` to reflect progress on time series and future tasks.

Author: tae898

.github/workflows/test-python-examples.yml

@@ -25,7 +25,7 @@ on:
         description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
         required: false
         type: string
-        default: "0[1-9]_*.py 1[0-6]_*.py"
+        default: "0[1-9]_*.py 1[0-7]_*.py"
       build-version:
         description: "Override package version (PEP 440) for build.sh"
         required: false
@@ -37,10 +37,10 @@ on:
       examples:
         description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
         required: false
-        default: "0[1-9]_*.py 1[0-6]_*.py"
+        default: "0[1-9]_*.py 1[0-7]_*.py"
 
 env:
-  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-6]_*.py' }}
+  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-7]_*.py' }}
 
 permissions:
   contents: read
@@ -396,6 +396,12 @@ jobs:
                 timeout_duration=1200
                 example_jvm_args=""
                 ;;
+              "17_timeseries_end_to_end.py")
+                example_args="--hours 2 --interval-minutes 10"
+                example_name="$example (time-series end-to-end, minimal)"
+                timeout_duration=900
+                example_jvm_args=""
+                ;;
               *)
                 example_args=""
                 example_name="$example"

bindings/python/docs/examples/13_stackoverflow_hybrid_queries.md

@@ -3,16 +3,18 @@
 [View source code]({{ config.repo_url }}/blob/{{ config.extra.version_tag }}/bindings/python/examples/13_stackoverflow_hybrid_queries.py){ .md-button }
 
 This example builds a standalone Stack Overflow pipeline combining document tables,
-property graph data, embeddings, vector indexes, and hybrid queries.
+property graph data, embeddings, vector indexes, hybrid queries, and a derived
+time-series activity layer.
 
 ## Overview
 
-Example 13 runs four phases:
+Example 13 runs five phases:
 
 1. XML to document tables
 2. XML to graph
 3. Embeddings plus vector indexes on Question, Answer, and Comment
 4. Hybrid queries combining SQL, OpenCypher, and vector search
+5. Derived time-series analytics from existing timestamped events
 
 ## Current Repository Guidance
 
@@ -24,6 +26,8 @@ Example 13 runs four phases:
 - `GraphBatch` is the repository's recommended bulk graph ingest path from Python
 - Graph edge creation uses RID-based directed endpoints
 - Traversal semantics are directional
+- Phase 5 does not replace the document or graph models; it builds a compact
+  `ActivitySeries` projection from existing `CreationDate` / `Date` fields
 
 ## Run
 
@@ -36,7 +40,8 @@ python 13_stackoverflow_hybrid_queries.py \
   --encode-batch-size 256 \
   --model all-MiniLM-L6-v2 \
   --heap-size 4g \
-  --top-k 10
+  --top-k 10 \
+  --timeseries-top-tags 5
 ```
 
 ## Key Options
@@ -48,3 +53,25 @@ python 13_stackoverflow_hybrid_queries.py \
 - `--heap-size`: JVM heap size
 - `--top-k`: hybrid/vector result count
 - `--candidate-limit`: candidate pool size for hybrid ranking
+- `--timeseries-top-tags`: number of top tags projected into the derived
+  time-series activity layer
+
+## Time-Series Layer
+
+The script now adds a compact derived TimeSeries type after the main hybrid phases:
+
+- `ActivitySeries`
+- timestamp: daily bucket timestamp
+- tags: `event_type`, `scope`, `tag`
+- fields: `event_count`, `total_score`, `avg_score`
+
+The source data comes from the timestamps already present on:
+
+- `Question.CreationDate`
+- `Answer.CreationDate`
+- `Comment.CreationDate`
+- `Badge.Date`
+
+That means the example stays faithful to the Stack Overflow domain model while also
+demonstrating how ArcadeDB can project graph/document events into a time-series view
+for trend analysis.

bindings/python/docs/examples/17_timeseries_end_to_end.md

@@ -0,0 +1,46 @@
+# 17 - Time Series End-to-End
+
+[View source code]({{ config.repo_url }}/blob/{{ config.extra.version_tag }}/bindings/python/examples/17_timeseries_end_to_end.py){ .md-button }
+
+This example demonstrates the current Python-bindings posture for time series:
+use plain ArcadeDB SQL from Python rather than a dedicated Python object API.
+
+It covers:
+
+- creating a `TIMESERIES TYPE` with multiple tags and numeric fields
+- generating deterministic telemetry for six building sensors
+- inserting hundreds of samples transactionally
+- running raw window queries with multiple tag filters
+- grouping into hourly buckets with `ts.timeBucket()`
+- aggregating at sensor, building, and region levels
+- deriving alert-style views from SQL aggregates
+- reading back the latest sample per sensor
+
+## Run
+
+From `bindings/python/examples`:
+
+```bash
+python3 17_timeseries_end_to_end.py
+```
+
+With a longer synthetic run:
+
+```bash
+python3 17_timeseries_end_to_end.py --hours 12 --interval-minutes 5
+```
+
+## Notes
+
+- The example is intentionally SQL-first.
+- If the packaged ArcadeDB runtime does not include TimeSeries SQL support,
+  the script prints a short explanation and exits.
+- The database is created under `./my_test_databases/timeseries_demo_db` and is kept for inspection.
+- The generated data models smart-building telemetry with tags for region, building,
+  zone, and sensor id plus fields for temperature, humidity, power, CO2, and occupancy.
+
+## Why SQL-First?
+
+The bindings already expose a stable generic interface through `db.command()` and
+`db.query()`. For time series, that keeps Python maintenance low while avoiding a
+premature public object API around upstream-owned semantics.

bindings/python/docs/examples/index.md

@@ -61,6 +61,9 @@ Four-way table-ingest comparison. Repository guidance from these experiments is
 **[16 - Import Database vs Transactional Graph Ingest](16_import_database_vs_transactional_graph_ingest.md)**
 Four-way graph-ingest comparison. Repository guidance from these experiments is to prefer `GraphBatch` for bulk graph ingest.
 
+**[17 - Time Series End-to-End](17_timeseries_end_to_end.md)**
+SQL-first time-series workflow covering type creation, tagged inserts, range queries, and hourly bucket aggregation.
+
 ## Quick Start
 
 **⚠️ Important: Always run examples from the `examples/` directory.**
@@ -83,6 +86,7 @@ python 01_simple_document_store.py
 9. **Vector Benchmarks** (11/12) - Index build and search benchmarking across vector backends
 10. **Hybrid Queries** (13) - Combined SQL, graph, and vector workflow
 11. **Lifecycle And Ingest Benchmarks** (14/15/16) - Embedded lifecycle timing and ingest comparisons
+12. **Time Series SQL Workflow** (17) - Tagged samples, range queries, and bucket aggregation from Python
 
 ---