@saibolla/ada 0.1.2

package/skills/datacommons-client/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: datacommons-client
+description: Work with Data Commons, a platform providing programmatic access to public statistical data from global sources. Use this skill when working with demographic data, economic indicators, health statistics, environmental data, or any public datasets available through Data Commons. Applicable for querying population statistics, GDP figures, unemployment rates, disease prevalence, geographic entity resolution, and exploring relationships between statistical entities.
+license: Unknown
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# Data Commons Client
+
+## Overview
+
+Provides comprehensive access to the Data Commons Python API v2 for querying statistical observations, exploring the knowledge graph, and resolving entity identifiers. Data Commons aggregates data from census bureaus, health organizations, environmental agencies, and other authoritative sources into a unified knowledge graph.
+
+## Installation
+
+Install the Data Commons Python client with Pandas support:
+
+```bash
+uv pip install "datacommons-client[Pandas]"
+```
+
+For basic usage without Pandas:
+```bash
+uv pip install datacommons-client
+```
+
+## Core Capabilities
+
+The Data Commons API consists of three main endpoints, each detailed in dedicated reference files:
+
+### 1. Observation Endpoint - Statistical Data Queries
+
+Query time-series statistical data for entities. See `references/observation.md` for comprehensive documentation.
+
+**Primary use cases:**
+- Retrieve population, economic, health, or environmental statistics
+- Access historical time-series data for trend analysis
+- Query data for hierarchies (all counties in a state, all countries in a region)
+- Compare statistics across multiple entities
+- Filter by data source for consistency
+
+**Common patterns:**
+```python
+from datacommons_client import DataCommonsClient
+
+client = DataCommonsClient()
+
+# Get latest population data
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["geoId/06"],  # California
+    date="latest"
+)
+
+# Get time series
+response = client.observation.fetch(
+    variable_dcids=["UnemploymentRate_Person"],
+    entity_dcids=["country/USA"],
+    date="all"
+)
+
+# Query by hierarchy
+response = client.observation.fetch(
+    variable_dcids=["MedianIncome_Household"],
+    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
+    date="2020"
+)
+```
+
+### 2. Node Endpoint - Knowledge Graph Exploration
+
+Explore entity relationships and properties within the knowledge graph. See `references/node.md` for comprehensive documentation.
+
+**Primary use cases:**
+- Discover available properties for entities
+- Navigate geographic hierarchies (parent/child relationships)
+- Retrieve entity names and metadata
+- Explore connections between entities
+- List all entity types in the graph
+
+**Common patterns:**
+```python
+# Discover properties
+labels = client.node.fetch_property_labels(
+    node_dcids=["geoId/06"],
+    out=True
+)
+
+# Navigate hierarchy
+children = client.node.fetch_place_children(
+    node_dcids=["country/USA"]
+)
+
+# Get entity names
+names = client.node.fetch_entity_names(
+    node_dcids=["geoId/06", "geoId/48"]
+)
+```
+
+### 3. Resolve Endpoint - Entity Identification
+
+Translate entity names, coordinates, or external IDs into Data Commons IDs (DCIDs). See `references/resolve.md` for comprehensive documentation.
+
+**Primary use cases:**
+- Convert place names to DCIDs for queries
+- Resolve coordinates to places
+- Map Wikidata IDs to Data Commons entities
+- Handle ambiguous entity names
+
+**Common patterns:**
+```python
+# Resolve by name
+response = client.resolve.fetch_dcids_by_name(
+    names=["California", "Texas"],
+    entity_type="State"
+)
+
+# Resolve by coordinates
+dcid = client.resolve.fetch_dcid_by_coordinates(
+    latitude=37.7749,
+    longitude=-122.4194
+)
+
+# Resolve Wikidata IDs
+response = client.resolve.fetch_dcids_by_wikidata_id(
+    wikidata_ids=["Q30", "Q99"]
+)
+```
+
+## Typical Workflow
+
+Most Data Commons queries follow this pattern:
+
+1. **Resolve entities** (if starting with names):
+   ```python
+   resolve_response = client.resolve.fetch_dcids_by_name(
+       names=["California", "Texas"]
+   )
+   dcids = [r["candidates"][0]["dcid"]
+            for r in resolve_response.to_dict().values()
+            if r["candidates"]]
+   ```
+
+2. **Discover available variables** (optional):
+   ```python
+   variables = client.observation.fetch_available_statistical_variables(
+       entity_dcids=dcids
+   )
+   ```
+
+3. **Query statistical data**:
+   ```python
+   response = client.observation.fetch(
+       variable_dcids=["Count_Person", "UnemploymentRate_Person"],
+       entity_dcids=dcids,
+       date="latest"
+   )
+   ```
+
+4. **Process results**:
+   ```python
+   # As dictionary
+   data = response.to_dict()
+
+   # As Pandas DataFrame
+   df = response.to_observations_as_records()
+   ```
+
+## Finding Statistical Variables
+
+Statistical variables use specific naming patterns in Data Commons:
+
+**Common variable patterns:**
+- `Count_Person` - Total population
+- `Count_Person_Female` - Female population
+- `UnemploymentRate_Person` - Unemployment rate
+- `Median_Income_Household` - Median household income
+- `Count_Death` - Death count
+- `Median_Age_Person` - Median age
+
+**Discovery methods:**
+```python
+# Check what variables are available for an entity
+available = client.observation.fetch_available_statistical_variables(
+    entity_dcids=["geoId/06"]
+)
+
+# Or explore via the web interface
+# https://datacommons.org/tools/statvar
+```
+
+## Working with Pandas
+
+All observation responses integrate with Pandas:
+
+```python
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["geoId/06", "geoId/48"],
+    date="all"
+)
+
+# Convert to DataFrame
+df = response.to_observations_as_records()
+# Columns: date, entity, variable, value
+
+# Reshape for analysis
+pivot = df.pivot_table(
+    values='value',
+    index='date',
+    columns='entity'
+)
+```
+
+## API Authentication
+
+**For datacommons.org (default):**
+- An API key is required
+- Set via environment variable: `export DC_API_KEY="your_key"`
+- Or pass when initializing: `client = DataCommonsClient(api_key="your_key")`
+- Request keys at: https://apikeys.datacommons.org/
+
+**For custom Data Commons instances:**
+- No API key required
+- Specify custom endpoint: `client = DataCommonsClient(url="https://custom.datacommons.org")`
+
+## Reference Documentation
+
+Comprehensive documentation for each endpoint is available in the `references/` directory:
+
+- **`references/observation.md`**: Complete Observation API documentation with all methods, parameters, response formats, and common use cases
+- **`references/node.md`**: Complete Node API documentation for graph exploration, property queries, and hierarchy navigation
+- **`references/resolve.md`**: Complete Resolve API documentation for entity identification and DCID resolution
+- **`references/getting_started.md`**: Quickstart guide with end-to-end examples and common patterns
+
+## Additional Resources
+
+- **Official Documentation**: https://docs.datacommons.org/api/python/v2/
+- **Statistical Variable Explorer**: https://datacommons.org/tools/statvar
+- **Data Commons Browser**: https://datacommons.org/browser/
+- **GitHub Repository**: https://github.com/datacommonsorg/api-python
+
+## Tips for Effective Use
+
+1. **Always start with resolution**: Convert names to DCIDs before querying data
+2. **Use relation expressions for hierarchies**: Query all children at once instead of individual queries
+3. **Check data availability first**: Use `fetch_available_statistical_variables()` to see what's queryable
+4. **Leverage Pandas integration**: Convert responses to DataFrames for analysis
+5. **Cache resolutions**: If querying the same entities repeatedly, store name→DCID mappings
+6. **Filter by facet for consistency**: Use `filter_facet_domains` to ensure data from the same source
+7. **Read reference docs**: Each endpoint has extensive documentation in the `references/` directory
+

package/skills/datacommons-client/references/getting_started.md

@@ -0,0 +1,417 @@
+# Getting Started with Data Commons
+
+## Quick Start Guide
+
+This guide provides end-to-end examples for common Data Commons workflows.
+
+## Installation and Setup
+
+```bash
+# Install with Pandas support
+pip install "datacommons-client[Pandas]"
+
+# Set up API key for datacommons.org
+export DC_API_KEY="your_api_key_here"
+```
+
+Request an API key at: https://apikeys.datacommons.org/
+
+## Example 1: Basic Population Query
+
+Query current population for specific places:
+
+```python
+from datacommons_client import DataCommonsClient
+
+# Initialize client
+client = DataCommonsClient()
+
+# Step 1: Resolve place names to DCIDs
+places = ["California", "Texas", "New York"]
+resolve_response = client.resolve.fetch_dcids_by_name(
+    names=places,
+    entity_type="State"
+)
+
+# Extract DCIDs
+dcids = []
+for name, result in resolve_response.to_dict().items():
+    if result["candidates"]:
+        dcids.append(result["candidates"][0]["dcid"])
+        print(f"{name}: {result['candidates'][0]['dcid']}")
+
+# Step 2: Query population data
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=dcids,
+    date="latest"
+)
+
+# Step 3: Display results
+data = response.to_dict()
+for variable, entities in data.items():
+    for entity, observations in entities.items():
+        for obs in observations:
+            print(f"{entity}: {obs['value']:,} people ({obs['date']})")
+```
+
+## Example 2: Time Series Analysis
+
+Retrieve and plot historical unemployment rates:
+
+```python
+import pandas as pd
+import matplotlib.pyplot as plt
+
+client = DataCommonsClient()
+
+# Query unemployment rate over time
+response = client.observation.fetch(
+    variable_dcids=["UnemploymentRate_Person"],
+    entity_dcids=["country/USA"],
+    date="all"  # Get all historical data
+)
+
+# Convert to DataFrame
+df = response.to_observations_as_records()
+
+# Plot
+df = df.sort_values('date')
+plt.figure(figsize=(12, 6))
+plt.plot(df['date'], df['value'])
+plt.title('US Unemployment Rate Over Time')
+plt.xlabel('Year')
+plt.ylabel('Unemployment Rate (%)')
+plt.grid(True)
+plt.show()
+```
+
+## Example 3: Geographic Hierarchy Query
+
+Get data for all counties within a state:
+
+```python
+client = DataCommonsClient()
+
+# Query median income for all California counties
+response = client.observation.fetch(
+    variable_dcids=["Median_Income_Household"],
+    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
+    date="2020"
+)
+
+# Convert to DataFrame and sort
+df = response.to_observations_as_records()
+
+# Get county names
+county_dcids = df['entity'].unique().tolist()
+names = client.node.fetch_entity_names(node_dcids=county_dcids)
+
+# Add names to dataframe
+df['name'] = df['entity'].map(names)
+
+# Display top 10 by income
+top_counties = df.nlargest(10, 'value')[['name', 'value']]
+print("\nTop 10 California Counties by Median Household Income:")
+for idx, row in top_counties.iterrows():
+    print(f"{row['name']}: ${row['value']:,.0f}")
+```
+
+## Example 4: Multi-Variable Comparison
+
+Compare multiple statistics across entities:
+
+```python
+import pandas as pd
+
+client = DataCommonsClient()
+
+# Define places
+places = ["California", "Texas", "Florida", "New York"]
+resolve_response = client.resolve.fetch_dcids_by_name(names=places)
+
+dcids = []
+name_map = {}
+for name, result in resolve_response.to_dict().items():
+    if result["candidates"]:
+        dcid = result["candidates"][0]["dcid"]
+        dcids.append(dcid)
+        name_map[dcid] = name
+
+# Query multiple variables
+variables = [
+    "Count_Person",
+    "Median_Income_Household",
+    "UnemploymentRate_Person",
+    "Median_Age_Person"
+]
+
+response = client.observation.fetch(
+    variable_dcids=variables,
+    entity_dcids=dcids,
+    date="latest"
+)
+
+# Convert to DataFrame
+df = response.to_observations_as_records()
+
+# Add readable names
+df['state'] = df['entity'].map(name_map)
+
+# Pivot for comparison
+pivot = df.pivot_table(
+    values='value',
+    index='state',
+    columns='variable'
+)
+
+print("\nState Comparison:")
+print(pivot.to_string())
+```
+
+## Example 5: Coordinate-Based Query
+
+Find and query data for a location by coordinates:
+
+```python
+client = DataCommonsClient()
+
+# User provides coordinates (e.g., from GPS)
+latitude, longitude = 37.7749, -122.4194  # San Francisco
+
+# Step 1: Resolve coordinates to place
+dcid = client.resolve.fetch_dcid_by_coordinates(
+    latitude=latitude,
+    longitude=longitude
+)
+
+# Step 2: Get place name
+name = client.node.fetch_entity_names(node_dcids=[dcid])
+print(f"Location: {name[dcid]}")
+
+# Step 3: Check available variables
+available_vars = client.observation.fetch_available_statistical_variables(
+    entity_dcids=[dcid]
+)
+
+print(f"\nAvailable variables: {len(available_vars[dcid])} found")
+print("First 10:", list(available_vars[dcid])[:10])
+
+# Step 4: Query specific variables
+response = client.observation.fetch(
+    variable_dcids=["Count_Person", "Median_Income_Household"],
+    entity_dcids=[dcid],
+    date="latest"
+)
+
+# Display results
+df = response.to_observations_as_records()
+print("\nStatistics:")
+for _, row in df.iterrows():
+    print(f"{row['variable']}: {row['value']}")
+```
+
+## Example 6: Data Source Filtering
+
+Query data from specific sources for consistency:
+
+```python
+client = DataCommonsClient()
+
+# Query with facet filtering
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["country/USA"],
+    date="all",
+    filter_facet_domains=["census.gov"]  # Only US Census data
+)
+
+df = response.to_observations_as_records()
+print(f"Found {len(df)} observations from census.gov")
+
+# Compare with all sources
+response_all = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["country/USA"],
+    date="all"
+)
+
+df_all = response_all.to_observations_as_records()
+print(f"Found {len(df_all)} observations from all sources")
+```
+
+## Example 7: Exploring the Knowledge Graph
+
+Discover entity properties and relationships:
+
+```python
+client = DataCommonsClient()
+
+# Step 1: Explore what properties exist
+entity = "geoId/06"  # California
+
+# Get outgoing properties
+out_props = client.node.fetch_property_labels(
+    node_dcids=[entity],
+    out=True
+)
+
+print(f"Outgoing properties for California:")
+print(out_props[entity])
+
+# Get incoming properties
+in_props = client.node.fetch_property_labels(
+    node_dcids=[entity],
+    out=False
+)
+
+print(f"\nIncoming properties for California:")
+print(in_props[entity])
+
+# Step 2: Get specific property values
+name_response = client.node.fetch_property_values(
+    node_dcids=[entity],
+    property="name",
+    out=True
+)
+
+print(f"\nName property value:")
+print(name_response.to_dict())
+
+# Step 3: Explore hierarchy
+children = client.node.fetch_place_children(node_dcids=[entity])
+print(f"\nNumber of child places: {len(children[entity])}")
+
+# Get names for first 5 children
+if children[entity]:
+    child_sample = children[entity][:5]
+    child_names = client.node.fetch_entity_names(node_dcids=child_sample)
+    print("\nSample child places:")
+    for dcid, name in child_names.items():
+        print(f"  {name}")
+```
+
+## Example 8: Batch Processing Multiple Queries
+
+Efficiently query data for many entities:
+
+```python
+import pandas as pd
+
+client = DataCommonsClient()
+
+# List of cities to analyze
+cities = [
+    "San Francisco, CA",
+    "Los Angeles, CA",
+    "San Diego, CA",
+    "Sacramento, CA",
+    "San Jose, CA"
+]
+
+# Resolve all cities
+resolve_response = client.resolve.fetch_dcids_by_name(
+    names=cities,
+    entity_type="City"
+)
+
+# Build mapping
+city_dcids = []
+dcid_to_name = {}
+for name, result in resolve_response.to_dict().items():
+    if result["candidates"]:
+        dcid = result["candidates"][0]["dcid"]
+        city_dcids.append(dcid)
+        dcid_to_name[dcid] = name
+
+# Query multiple variables at once
+variables = [
+    "Count_Person",
+    "Median_Income_Household",
+    "UnemploymentRate_Person"
+]
+
+response = client.observation.fetch(
+    variable_dcids=variables,
+    entity_dcids=city_dcids,
+    date="latest"
+)
+
+# Process into a comparison table
+df = response.to_observations_as_records()
+df['city'] = df['entity'].map(dcid_to_name)
+
+# Create comparison table
+comparison = df.pivot_table(
+    values='value',
+    index='city',
+    columns='variable',
+    aggfunc='first'
+)
+
+print("\nCalifornia Cities Comparison:")
+print(comparison.to_string())
+
+# Export to CSV
+comparison.to_csv('ca_cities_comparison.csv')
+print("\nData exported to ca_cities_comparison.csv")
+```
+
+## Common Patterns Summary
+
+### Pattern 1: Name → DCID → Data
+```python
+names = ["California"]
+dcids = resolve_names(names)
+data = query_observations(dcids, variables)
+```
+
+### Pattern 2: Coordinates → DCID → Data
+```python
+dcid = resolve_coordinates(lat, lon)
+data = query_observations([dcid], variables)
+```
+
+### Pattern 3: Parent → Children → Data
+```python
+children = get_place_children(parent_dcid)
+data = query_observations(children, variables)
+```
+
+### Pattern 4: Explore → Select → Query
+```python
+available_vars = check_available_variables(dcids)
+selected_vars = filter_relevant(available_vars)
+data = query_observations(dcids, selected_vars)
+```
+
+## Error Handling Best Practices
+
+```python
+client = DataCommonsClient()
+
+# Always check for candidates
+resolve_response = client.resolve.fetch_dcids_by_name(names=["Unknown Place"])
+result = resolve_response.to_dict()["Unknown Place"]
+
+if not result["candidates"]:
+    print("No matches found - try a more specific name")
+    # Handle error appropriately
+else:
+    dcid = result["candidates"][0]["dcid"]
+    # Proceed with query
+
+# Check for multiple candidates (ambiguity)
+if len(result["candidates"]) > 1:
+    print(f"Multiple matches found: {len(result['candidates'])}")
+    for candidate in result["candidates"]:
+        print(f"  {candidate['dcid']} ({candidate.get('dominantType', 'N/A')})")
+    # Let user select or use additional filtering
+```
+
+## Next Steps
+
+1. Explore available statistical variables: https://datacommons.org/tools/statvar
+2. Browse the knowledge graph: https://datacommons.org/browser/
+3. Read detailed endpoint documentation in `references/` directory
+4. Check official documentation: https://docs.datacommons.org/api/python/v2/