Expand Graph Once

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

1. Selects candidate moments from the existing graph
2. Uses AI to identify historically related events
3. Generates and indexes new moment nodes
4. Creates thematic edges between related moments
5. Expands the temporal and thematic coverage of the graph

​

Authentication

1. SERVICE_API_KEY header for authentication
2. OPENROUTER_API_KEY environment variable must be configured

X-Service-Key: your-service-api-key

​

Configuration Requirements

​

Request

curl -X POST https://api.clockchain.io/api/expand-once \
  -H "X-Service-Key: your-service-api-key"

​

Response

​

Example Request

curl -X POST https://api.clockchain.io/api/expand-once \
  -H "X-Service-Key: your-service-api-key"

​

Example Response

{
  "before": {
    "nodes": 1247,
    "edges": 3892
  },
  "after": {
    "nodes": 1253,
    "edges": 3910
  },
  "added_nodes": 6,
  "added_edges": 18
}

​

How Graph Expansion Works

​

1. Candidate Selection

• High-layer (quality) moments
• Moments with few existing connections
• Events in underrepresented time periods or regions
• Recently added moments that need context

​

2. Related Event Discovery

• Analyzes the historical context
• Identifies causally related events (causes and consequences)
• Finds thematically similar moments
• Discovers events involving the same figures or locations

​

3. Moment Generation

• Full moment data with verified dates and locations
• Character/figure extraction
• Historical context and grounding
• Tags and categorization

​

4. Edge Creation

• Seed moments and newly discovered moments
• Newly discovered moments that are related to each other
• Existing graph nodes that connect to new moments

• causal - Cause and effect relationships
• thematic - Shared themes or topics
• temporal - Sequential events in a series
• spatial - Events in the same location
• figural - Involving the same historical figures

​

5. Graph Integration

• Paths are computed following Clockchain conventions
• Metadata is normalized and validated
• Duplicate detection prevents re-adding existing moments
• Layer assignments reflect data quality

​

Expansion Metrics

​

Use Cases

​

Manual Graph Growth

# Trigger expansion after adding seed moments
curl -X POST https://api.clockchain.io/api/expand-once \
  -H "X-Service-Key: your-service-api-key"

# Check results
echo "Added nodes: $(jq '.added_nodes' response.json)"

​

Testing Expansion Algorithm

# Run multiple cycles to test expansion quality
for i in {1..5}; do
  echo "Expansion cycle $i"
  curl -X POST https://api.clockchain.io/api/expand-once \
    -H "X-Service-Key: your-service-api-key"
  sleep 60
done

​

Scheduled Expansion Worker

import requests
import time

API_URL = "https://api.clockchain.io/api/expand-once"
HEADERS = {"X-Service-Key": "your-service-api-key"}

while True:
    response = requests.post(API_URL, headers=HEADERS)
    data = response.json()
    
    print(f"Expansion complete: +{data['added_nodes']} nodes, +{data['added_edges']} edges")
    
    # Wait 5 minutes before next expansion
    time.sleep(300)

​

On-Demand Expansion After Import

# Import seed moments
curl -X POST https://api.clockchain.io/api/bulk-generate \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: your-key" \
  -H "X-Admin-Key: your-admin-key" \
  -d '{"queries": [...]}}'

# Wait for generation to complete
sleep 30

# Expand graph to discover related moments
curl -X POST https://api.clockchain.io/api/expand-once \
  -H "X-Service-Key: your-service-api-key"

​

Performance Considerations

​

Processing Time

• Single expansion cycle: 30-90 seconds
• Depends on number of candidates selected
• Flash API latency is the primary bottleneck
• Parallel processing may be added in future versions

​

Resource Usage

• Consumes OpenRouter API credits for expansion logic
• Consumes Flash API credits for moment generation
• Database writes for new nodes and edges
• Memory usage scales with graph size

​

Best Practices

1. Start Small: Begin with 50-100 high-quality seed moments before expanding
2. Monitor Growth: Track added_nodes and added_edges to ensure healthy expansion
3. Review Quality: Periodically review newly added moments for accuracy
4. Control Costs: Set budgets for API usage and monitor expansion frequency
5. Balance Coverage: Ensure expansion doesn’t over-focus on specific periods or regions

​

Expansion vs. Generation

​

Error Responses

​

Monitoring Expansion Health

• Growth rate: Nodes/edges added per cycle
• Density: Edges per node ratio (healthy: 2-4)
• Coverage: Distribution across time periods and regions
• Quality: Layer distribution of new nodes
• Cost: API credits consumed per cycle

​

Future Enhancements

• Expansion targeting (focus on specific eras/regions)
• Batch expansion (multiple cycles in one request)
• Expansion strategies (breadth-first vs. depth-first)
• Quality thresholds for candidate selection
• Parallel moment generation

​

Related Endpoints

• Generate - Create specific moments
• Index - Manually add moments
• Bulk Generate - Batch moment creation
• /api/stats - View current graph statistics