# Jobs, Tasks & Requirements

Understanding Cubit's data model is essential for making the most of the API. This page explains how the different entities relate to each other.

## The Data Hierarchy

```
+------------------------------------------------------------------+
|                         OCCUPATIONS                              |
|  923 jobs from O*NET covering the entire US labor market        |
|  Each has: scores, pillars, classification, industries          |
+------------------------------------------------------------------+
                              |
                              | 1:many
                              v
+------------------------------------------------------------------+
|                           TASKS                                  |
|  18,796 specific work activities                                |
|  Each has: 4 dimension scores, pillar scores, quadrant          |
+------------------------------------------------------------------+
                              |
                              | many:many
                              v
+------------------------------------------------------------------+
|                       REQUIREMENTS                               |
|  120 skills, abilities, and knowledge domains                   |
|  Each has: AI resilience score, description                     |
+------------------------------------------------------------------+
                              |
                              | many:many
                              v
+------------------------------------------------------------------+
|                        BENCHMARKS                                |
|  1.2M+ AI evaluations from HELM (13K questions x 95 models)    |
|  Each tests specific cognitive capabilities                     |
+------------------------------------------------------------------+
```

## Jobs (Occupations)

Jobs are the primary entity most users work with. Each represents a distinct occupation from the O\*NET taxonomy.

### Key Fields

| Field                                         | Description                               |
| --------------------------------------------- | ----------------------------------------- |
| `soc_code`                                    | O\*NET SOC code (e.g., "15-1252.00")      |
| `title`                                       | Occupation title                          |
| `automation_susceptibility_score`             | Overall AI exposure (0-100)               |
| `human_centric_resilience_score`              | Human necessity protection (0-100)        |
| `balanced_impact_score`                       | Net positioning (-100 to +100)            |
| `quadrant`                                    | Strategic classification                  |
| `major_group` / `minor_group` / `broad_group` | SOC hierarchy                             |
| `projected_growth`                            | BLS employment outlook                    |
| `keystone_skills`                             | Top 10 high-value, high-resilience skills |

### Accessing Jobs

```python
# Search by keyword
results = client.search_jobs("data scientist")

# Get full profile
job = client.get_job("15-2051.00")

# Semantic search (Enterprise)
results = client.search_jobs_semantic("careers helping people with mental health")
```

### SOC Code Format

O\*NET SOC codes follow a hierarchical structure:

```
15-1252.00
|  |    |
|  |    +-- Detailed occupation (2 digits)
|  +------- Broad occupation (4 digits: 15-1252)
+---------- Major group (2 digits: 15 = Computer & Math)
```

***

## Tasks

Tasks are specific work activities within an occupation. This is where Cubit's analysis is most granular.

### Key Fields

| Field          | Description                          |
| -------------- | ------------------------------------ |
| `task_id`      | Unique identifier                    |
| `task`         | Description of the work activity     |
| `importance`   | How central to the job (1-5)         |
| `relevance`    | Percentage of workers who perform it |
| `dimensions`   | Four foundational scores (0-10 each) |
| `pillars`      | Derived scores (0-1 each)            |
| `quadrant`     | Task-level classification            |
| `explanations` | Reasoning for each dimension score   |

### Accessing Tasks (Professional+)

```python
tasks = client.get_job_tasks(
    "15-1252.00",
    sort_by="ai_exposure_potential",
    sort_order="desc",
    limit=10,
    include_explanations=True
)

for task in tasks["tasks"]:
    print(f"\n{task['task']}")
    print(f"  Exposure: {task['pillars']['ai_exposure_potential']:.0%}")
    print(f"  Quadrant: {task['quadrant']}")
```

### Task Distribution

Each occupation has 15-30 tasks. Across the entire database:

| Quadrant                  | Count | Percentage |
| ------------------------- | ----- | ---------- |
| Transitional              | 8,036 | 43%        |
| Protected (Human-Centric) | 6,602 | 35%        |
| Automation                | 3,467 | 18%        |
| Augmentation              | 691   | 4%         |

***

## Requirements (Skills, Abilities, Knowledge)

Requirements are the cognitive capabilities needed to perform work. They bridge tasks to AI benchmarks.

### Three Categories

| Category      | Count | Description                                                 |
| ------------- | ----- | ----------------------------------------------------------- |
| **Skills**    | 35    | Developed capacities (Programming, Negotiation)             |
| **Abilities** | 52    | Enduring attributes (Deductive Reasoning, Manual Dexterity) |
| **Knowledge** | 33    | Domain expertise (Medicine, Engineering)                    |

### Key Fields

| Field                 | Description                           |
| --------------------- | ------------------------------------- |
| `element_id`          | O\*NET element ID (e.g., "2.A.1.a")   |
| `name`                | Requirement name                      |
| `type`                | "Skills", "Abilities", or "Knowledge" |
| `description`         | What it involves                      |
| `ai_resilience_score` | How resistant to AI (0-1)             |

### Accessing Requirements

```python
# List all requirements
skills = client.list_skills(type="skills", limit=50)

# Get detailed profile (Professional+)
skill = client.get_skill("2.B.3.e")  # Programming
print(f"AI Resilience: {skill['ai_resilience_score']:.0%}")

# Semantic search (Enterprise)
results = client.search_skills_semantic("ability to convince others")
```

### Most/Least AI-Resilient Requirements

**Highest Resilience** (hardest for AI):

* Negotiation (100%)
* Operations Analysis (100%)
* Speaking (98%)
* Management of Personnel Resources (97%)

**Lowest Resilience** (AI performs well):

* Quality Control Analysis (8%)
* Equipment Maintenance (10%)
* Control Precision (5%)
* Programming (26%)

***

## Keystone Skills

Keystone skills are requirements that are both **highly relevant to a job** and **highly resistant to AI**. They represent the durable core of human value in each occupation.

### Calculation

```
Combined Impact = Job Relevance x AI Resilience
```

Jobs with 10+ keystone skills retain clear human value even as AI automates other aspects.

### Accessing Keystone Skills

```python
job = client.get_job("15-1252.00")

print("Keystone Skills for Software Developers:")
for skill in job["keystone_skills"]:
    print(f"  {skill['name']}")
    print(f"    Job Relevance: {skill['job_relevance']:.0f}%")
    print(f"    AI Resilience: {skill['ai_resilience']:.0f}%")
    print(f"    Combined Impact: {skill['combined_impact']:.1f}")
```

***

## Benchmarks (Enterprise)

Benchmarks are individual AI evaluation instances from the HELM benchmark suite. They provide the empirical foundation for Demonstrated Capability scores.

### Key Fields

| Field              | Description                               |
| ------------------ | ----------------------------------------- |
| `input_id`         | Unique identifier                         |
| `benchmark_name`   | Source benchmark (MMLU, HellaSwag, etc.)  |
| `task_description` | What the evaluation tests                 |
| `skills_tested`    | Linked requirements with relevance scores |

### Accessing Benchmarks (Enterprise)

```python
# List benchmarks testing a specific skill
benchmarks = client.list_benchmarks(skill="Programming", limit=10)

for b in benchmarks["benchmarks"]:
    print(f"[{b['benchmark_name']}] {b['task_description'][:60]}...")

# Get benchmark detail
detail = client.get_benchmark("12345")
print(detail["skills_tested"])
```

***

## Entity Relationships

### Task -> Requirements (Graph)

Each task links to multiple requirements with relevance scores:

```
Task: "Develop software testing procedures"
  +-- Programming (relevance: 0.9)
  +-- Critical Thinking (relevance: 0.7)
  +-- Quality Control Analysis (relevance: 0.8)
  +-- Systems Evaluation (relevance: 0.6)
```

### Requirement -> Benchmarks (Graph)

Each requirement links to benchmarks that test it:

```
Programming (Skill)
  +-- HumanEval (code generation)
  +-- MBPP (Python problems)
  +-- APPS (competitive programming)
  +-- ...47 total benchmarks
```

### Score Propagation

Benchmark performance flows through this graph:

1. **Benchmark -> Requirement**: AI performance on benchmarks aggregates to requirements
2. **Requirement -> Task**: Requirement AI capability flows to tasks that need those requirements
3. **Task -> Job**: Task-level scores aggregate to jobs, weighted by importance

***

## Regional Data (Enterprise)

Cubit also provides MSA-level (Metropolitan Statistical Area) intelligence:

### Key Fields

| Field                   | Description                        |
| ----------------------- | ---------------------------------- |
| `msa_code`              | 5-digit MSA identifier             |
| `msa_name`              | Region name                        |
| `total_employment`      | Workers in the region              |
| `total_at_risk_wages`   | Annual wages in high-exposure jobs |
| `mean_automation_score` | Employment-weighted average        |

```python
# List California metros
regions = client.list_regions(state="CA", limit=10)

# Get LA detailed profile
la = client.get_region("31080", include_jobs=True)
print(f"At-risk wages: ${la['summary']['total_at_risk_wages']:,.0f}")
```

***

## Next Steps

* [Quadrant Classification](/core-concepts/quadrants.md) - The four strategic zones
* [Task-Level Analysis](/guides/task-analysis.md) - Working with tasks
* [API Reference](/api-reference/overview.md) - Complete endpoint documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/core-concepts/data-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.