@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/datacommons-client/references/node.md

@@ -0,0 +1,250 @@
+# Node Endpoint - Knowledge Graph Exploration
+
+## Purpose
+
+The Node endpoint retrieves property relationships and values from the Data Commons knowledge graph. It returns information about directed edges (properties) connecting nodes, enabling discovery of connections within the graph structure.
+
+## Core Capabilities
+
+The Node API performs three primary functions:
+1. Retrieve property labels associated with nodes
+2. Obtain values for specific properties across nodes
+3. Discover all connected nodes linked through relationships
+
+## Available Methods
+
+### 1. fetch()
+
+Retrieve properties using relation expressions with arrow notation.
+
+**Key Parameters:**
+- `node_dcids`: Target node identifier(s)
+- `expression`: Relation syntax using arrows (`->`, `<-`, `<-*`)
+- `all_pages`: Enable pagination (default: True)
+- `next_token`: Continue paginated results
+
+**Arrow Notation:**
+- `->`: Outgoing property (from node to value)
+- `<-`: Incoming property (from value to node)
+- `<-*`: Multi-hop incoming traversal
+
+**Example Usage:**
+```python
+from datacommons_client import DataCommonsClient
+
+client = DataCommonsClient()
+
+# Get outgoing properties from California
+response = client.node.fetch(
+    node_dcids=["geoId/06"],
+    expression="->name"
+)
+
+# Get incoming properties (what points to this node)
+response = client.node.fetch(
+    node_dcids=["geoId/06"],
+    expression="<-containedInPlace"
+)
+```
+
+### 2. fetch_property_labels()
+
+Get property labels without retrieving values—useful for discovering what properties exist.
+
+**Parameters:**
+- `node_dcids`: Node identifier(s)
+- `out`: Boolean—True for outgoing properties, False for incoming
+
+**Example Usage:**
+```python
+# Get all outgoing property labels for California
+labels = client.node.fetch_property_labels(
+    node_dcids=["geoId/06"],
+    out=True
+)
+
+# Get all incoming property labels
+labels = client.node.fetch_property_labels(
+    node_dcids=["geoId/06"],
+    out=False
+)
+```
+
+### 3. fetch_property_values()
+
+Obtain specific property values with optional filters.
+
+**Parameters:**
+- `node_dcids`: Node identifier(s)
+- `property`: Property name to query
+- `out`: Direction (True for outgoing, False for incoming)
+- `limit`: Maximum number of values to return
+
+**Example Usage:**
+```python
+# Get name property for California
+values = client.node.fetch_property_values(
+    node_dcids=["geoId/06"],
+    property="name",
+    out=True
+)
+```
+
+### 4. fetch_all_classes()
+
+List all entity types (Class nodes) in the Data Commons graph.
+
+**Example Usage:**
+```python
+classes = client.node.fetch_all_classes()
+```
+
+### 5. fetch_entity_names()
+
+Look up entity names by DCID in selected languages.
+
+**Parameters:**
+- `node_dcids`: Entity identifier(s)
+- `language`: Language code (default: "en")
+
+**Example Usage:**
+```python
+names = client.node.fetch_entity_names(
+    node_dcids=["geoId/06", "country/USA"],
+    language="en"
+)
+# Returns: {"geoId/06": "California", "country/USA": "United States"}
+```
+
+### 6. Place Hierarchy Methods
+
+These methods navigate geographic relationships:
+
+#### fetch_place_children()
+Get direct child places.
+
+**Example Usage:**
+```python
+# Get all states in USA
+children = client.node.fetch_place_children(
+    node_dcids=["country/USA"]
+)
+```
+
+#### fetch_place_descendants()
+Retrieve full child hierarchies (recursive).
+
+**Example Usage:**
+```python
+# Get all descendants of California (counties, cities, etc.)
+descendants = client.node.fetch_place_descendants(
+    node_dcids=["geoId/06"]
+)
+```
+
+#### fetch_place_parents()
+Get direct parent places.
+
+**Example Usage:**
+```python
+# Get parent of San Francisco
+parents = client.node.fetch_place_parents(
+    node_dcids=["geoId/0667000"]
+)
+```
+
+#### fetch_place_ancestors()
+Retrieve complete parent lineages.
+
+**Example Usage:**
+```python
+# Get all ancestors of San Francisco (CA, USA, etc.)
+ancestors = client.node.fetch_place_ancestors(
+    node_dcids=["geoId/0667000"]
+)
+```
+
+### 7. fetch_statvar_constraints()
+
+Access constraint properties for statistical variables—useful for understanding variable definitions and constraints.
+
+**Example Usage:**
+```python
+constraints = client.node.fetch_statvar_constraints(
+    node_dcids=["Count_Person"]
+)
+```
+
+## Response Format
+
+Methods return either:
+- **NodeResponse objects** with `.to_dict()`, `.to_json()`, and `.nextToken` properties
+- **Dictionaries** for entity names and place hierarchy methods
+
+## Pagination
+
+For large responses:
+1. Set `all_pages=False` to receive data in chunks
+2. Response includes a `nextToken` value
+3. Re-query using that token to fetch subsequent pages
+
+**Example:**
+```python
+# First page
+response = client.node.fetch(
+    node_dcids=["country/USA"],
+    expression="<-containedInPlace",
+    all_pages=False
+)
+
+# Get next page if available
+if response.nextToken:
+    next_response = client.node.fetch(
+        node_dcids=["country/USA"],
+        expression="<-containedInPlace",
+        next_token=response.nextToken
+    )
+```
+
+## Common Use Cases
+
+### Use Case 1: Explore Available Properties
+
+```python
+# Discover what properties an entity has
+labels = client.node.fetch_property_labels(
+    node_dcids=["geoId/06"],
+    out=True
+)
+print(labels)  # Shows all outgoing properties like 'name', 'latitude', etc.
+```
+
+### Use Case 2: Navigate Geographic Hierarchies
+
+```python
+# Get all counties in California
+counties = client.node.fetch_place_children(
+    node_dcids=["geoId/06"]
+)
+
+# Filter for specific type if needed
+county_dcids = [child for child in counties["geoId/06"]
+                if "County" in child]
+```
+
+### Use Case 3: Build Entity Relationships
+
+```python
+# Find all entities that reference a specific node
+references = client.node.fetch(
+    node_dcids=["geoId/06"],
+    expression="<-location"
+)
+```
+
+## Important Notes
+
+- Use `fetch_property_labels()` first to discover available properties
+- The Node API cannot resolve complex relation expressions—use simpler expressions or break into multiple queries
+- For linked entity properties with arc relationships, combine Node API queries with Observation API
+- Place hierarchy methods return dictionaries, not NodeResponse objects

package/bin/skills/datacommons-client/references/observation.md

@@ -0,0 +1,185 @@
+# Observation Endpoint - Statistical Data Queries
+
+## Purpose
+
+The Observation API retrieves statistical observations—data points linking entities, variables, and specific dates. Examples include:
+- "USA population in 2020"
+- "California GDP over time"
+- "Unemployment rate for all counties in a state"
+
+## Core Methods
+
+### 1. fetch()
+
+Primary method for retrieving observations with flexible entity specification.
+
+**Key Parameters:**
+- `variable_dcids` (required): List of statistical variable identifiers
+- `entity_dcids` or `entity_expression` (required): Specify entities by ID or relation expression
+- `date` (optional): Defaults to "latest". Accepts:
+  - ISO-8601 format (e.g., "2020", "2020-01", "2020-01-15")
+  - "all" for complete time series
+  - "latest" for most recent data
+- `select` (optional): Controls returned fields
+  - Default: `["date", "entity", "variable", "value"]`
+  - Alternative: `["entity", "variable", "facet"]` to check availability without data
+- `filter_facet_domains`: Filter by data source domain
+- `filter_facet_ids`: Filter by specific facet IDs
+
+**Response Structure:**
+Data organized hierarchically by variable → entity, with metadata about "facets" (data sources) including:
+- Provenance URLs
+- Measurement methods
+- Observation periods
+- Import names
+
+**Example Usage:**
+```python
+from datacommons_client import DataCommonsClient
+
+client = DataCommonsClient()
+
+# Get latest population for multiple entities
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["geoId/06", "geoId/48"],  # California and Texas
+    date="latest"
+)
+
+# Get complete time series
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["country/USA"],
+    date="all"
+)
+
+# Use relation expressions to query hierarchies
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
+    date="2020"
+)
+```
+
+### 2. fetch_available_statistical_variables()
+
+Discovers which statistical variables contain data for given entities.
+
+**Input:** Entity DCIDs only
+**Output:** Dictionary of available variables organized by entity
+
+**Example Usage:**
+```python
+# Check what variables are available for California
+available = client.observation.fetch_available_statistical_variables(
+    entity_dcids=["geoId/06"]
+)
+```
+
+### 3. fetch_observations_by_entity_dcid()
+
+Explicit method targeting specific entities by DCID (functionally equivalent to `fetch()` with entity_dcids).
+
+### 4. fetch_observations_by_entity_type()
+
+Retrieves observations for multiple entities grouped by parent and type—useful for querying all countries in a region or all counties within a state.
+
+**Parameters:**
+- `parent_entity`: Parent entity DCID
+- `entity_type`: Type of child entities
+- `variable_dcids`: Statistical variables to query
+- `date`: Time specification
+- `select` and filter options
+
+**Example Usage:**
+```python
+# Get population for all counties in California
+response = client.observation.fetch_observations_by_entity_type(
+    parent_entity="geoId/06",
+    entity_type="County",
+    variable_dcids=["Count_Person"],
+    date="2020"
+)
+```
+
+## Response Object Methods
+
+All response objects support:
+- `to_json()`: Format as JSON string
+- `to_dict()`: Return as dictionary
+- `get_data_by_entity()`: Reorganize by entity instead of variable
+- `to_observations_as_records()`: Flatten into individual records
+
+## Common Use Cases
+
+### Use Case 1: Check Data Availability Before Querying
+
+Use `select=["entity", "variable"]` to confirm entities have observations without retrieving actual data:
+```python
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["geoId/06"],
+    select=["entity", "variable"]
+)
+```
+
+### Use Case 2: Access Complete Time Series
+
+Request `date="all"` to obtain complete historical observations for trend analysis:
+```python
+response = client.observation.fetch(
+    variable_dcids=["Count_Person", "UnemploymentRate_Person"],
+    entity_dcids=["country/USA"],
+    date="all"
+)
+```
+
+### Use Case 3: Filter by Data Source
+
+Specify `filter_facet_domains` to retrieve data from specific sources for consistency:
+```python
+response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=["country/USA"],
+    filter_facet_domains=["census.gov"]
+)
+```
+
+### Use Case 4: Query Hierarchical Relationships
+
+Use relation expressions to fetch observations for related entities:
+```python
+# Get data for all counties within California
+response = client.observation.fetch(
+    variable_dcids=["MedianIncome_Household"],
+    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
+    date="2020"
+)
+```
+
+## Working with Pandas
+
+The API integrates seamlessly with Pandas. Install with Pandas support:
+```bash
+pip install "datacommons-client[Pandas]"
+```
+
+Response objects can be converted to DataFrames for analysis:
+```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()
+# Returns DataFrame with columns: date, entity, variable, value
+```
+
+## Important Notes
+
+- **facets** represent data sources and include provenance metadata
+- **orderedFacets** are sorted by reliability/recency
+- Use relation expressions for complex graph queries
+- The `fetch()` method is the most flexible—use it for most queries

package/bin/skills/datacommons-client/references/resolve.md

@@ -0,0 +1,246 @@
+# Resolve Endpoint - Entity Identification
+
+## Purpose
+
+The Resolve API identifies Data Commons IDs (DCIDs) for entities in the knowledge graph. DCIDs are required for most queries in the Data Commons API, so resolution is typically the first step in any workflow.
+
+## Key Capabilities
+
+The endpoint currently supports **place entities only** and allows resolution through multiple methods:
+- **By name**: Search using descriptive terms like "San Francisco, CA"
+- **By Wikidata ID**: Lookup using external identifiers (e.g., "Q30" for USA)
+- **By coordinates**: Locate places via latitude/longitude
+- **By relation expressions**: Advanced searches using synthetic attributes
+
+## Available Methods
+
+### 1. fetch()
+
+General resolution using relation expressions—most flexible method.
+
+**Parameters:**
+- `nodes`: List of search terms or identifiers
+- `property`: Property to search (e.g., "name", "wikidataId")
+
+**Example Usage:**
+```python
+from datacommons_client import DataCommonsClient
+
+client = DataCommonsClient()
+
+# Resolve by name
+response = client.resolve.fetch(
+    nodes=["California", "Texas"],
+    property="name"
+)
+```
+
+### 2. fetch_dcids_by_name()
+
+Name-based lookup with optional type filtering—most commonly used method.
+
+**Parameters:**
+- `names`: List of place names to resolve
+- `entity_type`: Optional type filter (e.g., "City", "State", "County")
+
+**Returns:** `ResolveResponse` object with candidates for each name
+
+**Example Usage:**
+```python
+# Basic name resolution
+response = client.resolve.fetch_dcids_by_name(
+    names=["San Francisco, CA", "Los Angeles"]
+)
+
+# With type filtering
+response = client.resolve.fetch_dcids_by_name(
+    names=["San Francisco"],
+    entity_type="City"
+)
+
+# Access results
+for name, result in response.to_dict().items():
+    print(f"{name}: {result['candidates']}")
+```
+
+### 3. fetch_dcids_by_wikidata_id()
+
+Wikidata ID resolution for entities with known Wikidata identifiers.
+
+**Parameters:**
+- `wikidata_ids`: List of Wikidata IDs (e.g., "Q30", "Q99")
+
+**Example Usage:**
+```python
+# Resolve Wikidata IDs
+response = client.resolve.fetch_dcids_by_wikidata_id(
+    wikidata_ids=["Q30", "Q99"]  # USA and California
+)
+```
+
+### 4. fetch_dcid_by_coordinates()
+
+Geographic coordinate lookup to find the place at specific lat/long coordinates.
+
+**Parameters:**
+- `latitude`: Latitude coordinate
+- `longitude`: Longitude coordinate
+
+**Returns:** Single DCID string for the place at those coordinates
+
+**Example Usage:**
+```python
+# Find place at coordinates
+dcid = client.resolve.fetch_dcid_by_coordinates(
+    latitude=37.7749,
+    longitude=-122.4194
+)
+# Returns DCID for San Francisco
+```
+
+## Response Structure
+
+All methods (except `fetch_dcid_by_coordinates`) return a `ResolveResponse` object containing:
+- **node**: The search term provided
+- **candidates**: List of matching DCIDs with optional metadata
+  - Each candidate may include `dominantType` field for disambiguation
+- **Helper methods**:
+  - `to_dict()`: Full response as dictionary
+  - `to_json()`: JSON string format
+  - `to_flat_dict()`: Simplified format with just DCIDs
+
+**Example Response:**
+```python
+response = client.resolve.fetch_dcids_by_name(names=["Springfield"])
+
+# May return multiple candidates since many cities named Springfield exist
+# {
+#   "Springfield": {
+#     "candidates": [
+#       {"dcid": "geoId/1767000", "dominantType": "City"},  # Springfield, IL
+#       {"dcid": "geoId/2567000", "dominantType": "City"},  # Springfield, MA
+#       ...
+#     ]
+#   }
+# }
+```
+
+## Common Use Cases
+
+### Use Case 1: Resolve Place Names Before Querying
+
+Most workflows start by resolving names to DCIDs:
+```python
+# Step 1: Resolve names
+resolve_response = client.resolve.fetch_dcids_by_name(
+    names=["California", "Texas"]
+)
+
+# Step 2: Extract DCIDs
+dcids = []
+for name, result in resolve_response.to_dict().items():
+    if result["candidates"]:
+        dcids.append(result["candidates"][0]["dcid"])
+
+# Step 3: Query data using DCIDs
+data_response = client.observation.fetch(
+    variable_dcids=["Count_Person"],
+    entity_dcids=dcids,
+    date="latest"
+)
+```
+
+### Use Case 2: Handle Ambiguous Names
+
+When multiple candidates exist, use `dominantType` or be more specific:
+```python
+# Ambiguous name
+response = client.resolve.fetch_dcids_by_name(names=["Springfield"])
+candidates = response.to_dict()["Springfield"]["candidates"]
+
+# Filter by type or choose based on context
+city_candidates = [c for c in candidates if c.get("dominantType") == "City"]
+
+# Or be more specific in the query
+response = client.resolve.fetch_dcids_by_name(
+    names=["Springfield, Illinois"],
+    entity_type="City"
+)
+```
+
+### Use Case 3: Batch Resolution
+
+Resolve multiple entities efficiently:
+```python
+places = [
+    "San Francisco, CA",
+    "Los Angeles, CA",
+    "San Diego, CA",
+    "Sacramento, CA"
+]
+
+response = client.resolve.fetch_dcids_by_name(names=places)
+
+# Build mapping of name to DCID
+name_to_dcid = {}
+for name, result in response.to_dict().items():
+    if result["candidates"]:
+        name_to_dcid[name] = result["candidates"][0]["dcid"]
+```
+
+### Use Case 4: Coordinate-Based Queries
+
+Find the administrative place for a location:
+```python
+# User provides coordinates, find the place
+latitude, longitude = 37.7749, -122.4194
+dcid = client.resolve.fetch_dcid_by_coordinates(
+    latitude=latitude,
+    longitude=longitude
+)
+
+# Now query data for that place
+response = client.observation.fetch(
+    variable_dcids=["Count_Person", "MedianIncome_Household"],
+    entity_dcids=[dcid],
+    date="latest"
+)
+```
+
+### Use Case 5: External ID Integration
+
+When working with external datasets that use Wikidata IDs:
+```python
+# External dataset has Wikidata IDs
+wikidata_ids = ["Q30", "Q99", "Q1384"]  # USA, California, New York
+
+# Convert to Data Commons DCIDs
+response = client.resolve.fetch_dcids_by_wikidata_id(
+    wikidata_ids=wikidata_ids
+)
+
+# Extract DCIDs for further queries
+dcids = []
+for wid, result in response.to_dict().items():
+    if result["candidates"]:
+        dcids.append(result["candidates"][0]["dcid"])
+```
+
+## Important Limitations
+
+1. **Place entities only**: The Resolve API currently supports only place entities (countries, states, cities, counties, etc.). For other entity types, DCIDs must be obtained through other means (e.g., Node API exploration).
+
+2. **Cannot resolve linked entity properties**: For queries involving relationships like `containedInPlace`, use the Node API instead.
+
+3. **Ambiguity handling**: When multiple candidates exist, the API returns all matches. The application must decide which is correct based on context or additional filtering.
+
+## Best Practices
+
+1. **Always resolve names first**: Never assume DCID format—always use the Resolve API
+2. **Cache resolutions**: If querying the same places repeatedly, cache name→DCID mappings
+3. **Handle ambiguity**: Check for multiple candidates and use `entity_type` filtering or more specific names
+4. **Validate results**: Always check that `candidates` list is not empty before accessing DCIDs
+5. **Use appropriate method**:
+   - Names → `fetch_dcids_by_name()`
+   - Coordinates → `fetch_dcid_by_coordinates()`
+   - Wikidata IDs → `fetch_dcids_by_wikidata_id()`