> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumtyme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CIL Quickstart

This quickstart guide enables you to model complex multiscale systems, such as financial markets, with no reliance on training data.

The CIL models directional changes as a continuous causal chain, eliminating the need for historical training data while providing a deterministic view of system evolution.

In this guide you will learn:

* **Identification:** How to pinpoint system changes at their exact point of inception within the microscale.
* **Tracking:** How to follow an initial causal signal's evolution across multiple scales with zero information loss.

## Prerequisites

#### 1. Create a Virtual Environment

We recommend using a virtual environment to prevent dependency conflicts with other projects.

On Windows:

```bash theme={null}
python -m venv venv
venv\Scripts\activate
```

On Mac:

```bash theme={null}
python3 -m venv venv
source venv/bin/activate
```

#### 2. Install the Package

Once your environment is active, install the sumtyme python library.

```bash theme={null}
pip install sumtyme
```

<Note>
  The sumtyme package provides the underlying engine for detecting directional changes and analysing multiscale systems without requiring external training datasets.
</Note>

#### 3. Verify Installation

You can quickly verify that the package is ready for use by checking the version in your terminal:

```bash theme={null}
  python -c "import sumtyme; print(sumtyme.__version__)"
```

## Gold Price Volatility Analysis (Oct 2025)

| Metric             | Description                                              |
| ------------------ | -------------------------------------------------------- |
| Market Context     | Gold reached record highs followed by an 11% correction. |
| Asset Under Review | SPDR Gold Trust (GLD)                                    |
| Analysis Period    | October 20 to October 28, 2025                           |
| Peak Price         | 403.30 (Recorded Oct 20, 19:59)                          |
| Trough Price       | 357.62 (Recorded Oct 28, 09:08)                          |
| Maximum Drawdown   | 11.32%                                                   |

### Phase 1: Pinpointing Microscale Inception

<Note>
  Detect the exact moment a change starts at the micro-level before it is visible in macro data.
</Note>

```python theme={null}

  import pandas as pd 

  # 1. Fetch data
  gold_data = pd.read_csv('https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1s_reactive_outputs.csv', parse_dates=['datetime'])

  # 2. Date to start analysis  
  analysis_start_date = pd.to_datetime("2025-10-20 20:00:00")

  # 3. Filter data
  mask = gold_data['datetime'] >= analysis_start_date
  filtered_df = gold_data.loc[mask].reset_index(drop=True)

  print(f"Starting simulation for {len(filtered_df)} data points...")

  # 4. Simulate the API calls 
  filtered_data = filtered_df.to_dict('records')

  for current_tick in filtered_data:
      # Extracting variables
      timestamp = current_tick['datetime']
      price = current_tick['open']

      chain_detected = current_tick.get('chain_detected') 

      if chain_detected == -1:
          print(f"--- Event Detected at {timestamp} ---")
          print(f"Price: ${price}")
          break
```

### Phase 2: Mapping Multiscale Signal Propagation

<Note>
  Follow the signal as it moves across scales, evolving from a minor fluctuation into a significant trend.
</Note>

```python theme={null}

  import sumtyme 
  
  client = sumtyme.client(apikey='xxxxxxx')

  # 1. Define the data hierarchy (Granularity Scales)
  # Each tuple contains the URL to a specific timeframe's CSV and its label.
  # This setup allows the system to analyse how events cascade from 1-second ticks up to 10 minute timeframe.
  scales = [
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1s_reactive_outputs.csv", '1s'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5s_reactive_outputs.csv", '5s'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_15s_reactive_outputs.csv", '15s'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_30s_reactive_outputs.csv", '30s'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1m_reactive_outputs.csv", '1m'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_2m_reactive_outputs.csv", '2m'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5m_reactive_outputs.csv", '5m'),
      ("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_10m_reactive_outputs.csv", '10m'),
  ]

  # 2. Execute Causal Mapping
  # initial_chain_starts: Specific datetime where a chain first started.
  # causal_chain_details: A detailed breakdown of how the signal moved across different timeframes.
  initial_chain_starts, causal_chain_details = client.map_causal_chains(scales)

  # 3. Output results for review
  print("--- Chain Inception Points ---")
  print(initial_chain_starts[initial_chain_starts['propagation_id'] == 'Chain_2'])

  print("\n--- Detailed Causal Path Analysis ---")
  print(causal_chain_details[causal_chain_details['propagation_id']=='Chain_2'])
```

### Result

The CIL framework successfully identified the structural breakdown of the Gold (GLD) market within seconds of its microscale inception, well before the trend became visible to traditional macro indicators.

| Metric                          | Details                 |
| :------------------------------ | :---------------------- |
| **Detection Status**            | Negative Chain Detected |
| **Initial Detection Price**     | 402.31                  |
| **Detection Timestamp**         | 2025-10-20 20:02:02     |
| **Price Drop Before Detection** | 0.99 (from 403.30)      |
| **Time to Detection**           | 2 minutes, 48 seconds   |
| **Drawdown Saved**              | 99.85%                  |

The robustness of the CIL approach is evidenced by Propagation ID: Chain\_2. The signal's ability to propagate through every timeframe confirms it was a systemic shift rather than random noise:

* **Micro-confirmation (1s – 30s)**: The signal survived the initial volatility phase, confirming a structural directional shift at the earliest possible stage.
* **Macro-realisation (1m – 10m)**: The chain remained intact across all scales, by the time it reached the 10m scale on Oct 28, the market had realised the full 11% correction.
* **Zero Information Loss**: Each scale transition maintained the original -1 (negative) directionality, validating the deterministic nature of the causal chain.