feat: scope threading + population-scope-aware sampling

Thread `scope` (individual/household) through the full spec builder
pipeline: selector → hydrators → binder → AttributeSpec. Add
`agent_focus` extraction in sufficiency check, propagated through
SpecMeta to the sampler.

Sampler now classifies agent_focus into three modes:
- "all" (families): everyone is an agent, kids promoted to full agents
- "couples" (retired couples): both partners are agents, kids are NPCs
- "primary_only" (surgeons, students): only primary adult is agent,
  partner becomes NPC context attached to agent

New sampler functions: _classify_agent_focus, _generate_npc_partner,
_sample_dependent_as_agent. Household sampling loop branches on focus
mode for partner and dependent handling.

Author: DeveshParagiri

extropy/cli/commands/spec.py

@@ -64,8 +64,12 @@ def spec_command(
 
     size = sufficiency_result.size
     geography = sufficiency_result.geography
+    agent_focus = sufficiency_result.agent_focus
     geo_str = f", {geography}" if geography else ""
-    console.print(f"[green]✓[/green] Context sufficient ({size} agents{geo_str})")
+    focus_str = f", focus: {agent_focus}" if agent_focus else ""
+    console.print(
+        f"[green]✓[/green] Context sufficient ({size} agents{geo_str}{focus_str})"
+    )
 
     # Step 1: Attribute Selection
     console.print()
@@ -207,6 +211,7 @@ def do_hydration():
             attributes=bound_attrs,
             sampling_order=sampling_order,
             sources=sources,
+            agent_focus=agent_focus,
         )
 
     console.print("[green]✓[/green] Spec assembled")

extropy/core/models/population.py

@@ -304,6 +304,10 @@ class SpecMeta(BaseModel):
     description: str = Field(description="Original population description")
     size: int = Field(description="Number of agents to generate")
     geography: str | None = Field(default=None, description="Geographic scope")
+    agent_focus: str | None = Field(
+        default=None,
+        description="Who the study agents represent. Determines agent vs NPC partitioning in household sampling.",
+    )
     created_at: datetime = Field(default_factory=datetime.now)
     version: str = Field(default="1.0", description="Spec format version")
     persona_template: str | None = Field(
@@ -460,6 +464,7 @@ def merge(self, extension: "PopulationSpec") -> "PopulationSpec":
             description=f"{self.meta.description} + {extension.meta.description}",
             size=self.meta.size,
             geography=self.meta.geography,
+            agent_focus=self.meta.agent_focus,
             created_at=datetime.now(),
             version=self.meta.version,
             persona_template=None,
@@ -536,6 +541,10 @@ class DiscoveredAttribute(BaseModel):
         default="independent",
         description="independent: sample directly; derived: zero-variance formula; conditional: probabilistic dependency",
     )
+    scope: Literal["individual", "household"] = Field(
+        default="individual",
+        description="individual: varies per person; household: shared across household members",
+    )
     depends_on: list[str] = Field(default_factory=list)
 
 
@@ -558,6 +567,10 @@ class HydratedAttribute(BaseModel):
     strategy: Literal["independent", "derived", "conditional"] = Field(
         default="independent", description="Sampling strategy determined in Step 1"
     )
+    scope: Literal["individual", "household"] = Field(
+        default="individual",
+        description="individual: varies per person; household: shared across household members",
+    )
     depends_on: list[str] = Field(default_factory=list)
     sampling: SamplingConfig
     grounding: GroundingInfo
@@ -570,4 +583,8 @@ class SufficiencyResult(BaseModel):
     sufficient: bool
     size: int = Field(default=1000, description="Extracted or default population size")
     geography: str | None = None
+    agent_focus: str | None = Field(
+        default=None,
+        description="Who this study is about, e.g. 'surgeons', 'high school students', 'retired couples', 'families'",
+    )
     clarifications_needed: list[str] = Field(default_factory=list)

extropy/population/sampler/core.py

@@ -14,7 +14,7 @@
 import sqlite3
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from ...core.models import (
     PopulationSpec,
@@ -47,6 +47,30 @@ class SamplingError(Exception):
     pass
 
 
+def _classify_agent_focus(
+    agent_focus: str | None,
+) -> Literal["all", "couples", "primary_only"]:
+    """Determine household agent scope from agent_focus metadata.
+
+    Returns:
+        "all" — everyone in household is an agent (families, communities)
+        "couples" — both partners are agents, kids are NPCs (retired couples, married couples)
+        "primary_only" — only the primary adult is an agent, partner + kids are NPCs (surgeons, students, subscribers)
+    """
+    if not agent_focus:
+        return "primary_only"
+
+    focus_lower = agent_focus.lower()
+
+    if any(kw in focus_lower for kw in ("famil", "household", "everyone")):
+        return "all"
+
+    if any(kw in focus_lower for kw in ("couple", "pair", "partners", "spouses")):
+        return "couples"
+
+    return "primary_only"
+
+
 def _has_household_attributes(spec: PopulationSpec) -> bool:
     """Check if the spec has household-scoped attributes, indicating household mode."""
     return any(attr.scope == "household" for attr in spec.attributes)
@@ -177,6 +201,83 @@ def _sample_population_independent(
     return agents
 
 
+def _generate_npc_partner(
+    primary: dict[str, Any],
+    household_attrs: set[str],
+    categorical_options: dict[str, list[str]],
+    rng: random.Random,
+) -> dict[str, Any]:
+    """Generate a lightweight NPC partner profile for context.
+
+    Not a full agent — just enough for persona prompts and conversations.
+    """
+    partner: dict[str, Any] = {}
+
+    if "age" in primary:
+        partner["age"] = correlate_partner_attribute("age", primary["age"], rng)
+    partner["gender"] = rng.choice(["male", "female"])
+
+    for attr in (
+        "race_ethnicity",
+        "education_level",
+        "religious_affiliation",
+        "political_orientation",
+    ):
+        if attr in primary:
+            correlated = correlate_partner_attribute(
+                attr, primary[attr], rng, categorical_options.get(attr)
+            )
+            if correlated is not None:
+                partner[attr] = correlated
+
+    # Shared household attrs
+    for attr in household_attrs:
+        if attr in primary:
+            partner[attr] = primary[attr]
+
+    if primary.get("last_name"):
+        partner["last_name"] = primary["last_name"]
+
+    partner["relationship"] = "partner"
+    return partner
+
+
+def _sample_dependent_as_agent(
+    spec: PopulationSpec,
+    attr_map: dict[str, AttributeSpec],
+    rng: random.Random,
+    index: int,
+    id_width: int,
+    stats: SamplingStats,
+    numeric_values: dict[str, list[float]],
+    dependent: Any,
+    parent: dict[str, Any],
+    household_id: str,
+) -> dict[str, Any]:
+    """Promote a dependent to a full agent with all attributes sampled.
+
+    Uses the dependent's known attributes (age, gender) as seeds,
+    then samples remaining attributes normally.
+    """
+    agent = _sample_single_agent(
+        spec, attr_map, rng, index, id_width, stats, numeric_values
+    )
+
+    # Override with dependent's known attributes
+    agent["age"] = dependent.age
+    agent["gender"] = dependent.gender
+    agent["household_id"] = household_id
+    agent["household_role"] = f"dependent_{dependent.relationship}"
+    agent["relationship_to_primary"] = dependent.relationship
+
+    # Copy household-scoped attributes from parent
+    for attr in spec.attributes:
+        if attr.scope == "household" and attr.name in parent:
+            agent[attr.name] = parent[attr.name]
+
+    return agent
+
+
 def _sample_population_households(
     spec: PopulationSpec,
     attr_map: dict[str, AttributeSpec],
@@ -192,6 +293,8 @@ def _sample_population_households(
     Returns (agents, households) where households is a list of household
     metadata dicts for DB persistence.
     """
+    focus_mode = _classify_agent_focus(spec.meta.agent_focus)
+
     num_households = estimate_household_count(target_n)
     hh_id_width = len(str(num_households - 1))
 
@@ -216,7 +319,7 @@ def _sample_population_households(
 
         household_id = f"household_{hh_idx:0{hh_id_width}d}"
 
-        # Sample Adult 1 (primary)
+        # Sample Adult 1 (primary) — always an agent
         adult1 = _sample_single_agent(
             spec, attr_map, rng, agent_index, id_width, stats, numeric_values
         )
@@ -244,45 +347,81 @@ def _sample_population_households(
         adult1["household_role"] = "adult_primary"
 
         adult_ids = [adult1["_id"]]
-
-        if has_partner and agent_index < target_n:
-            # Sample Adult 2 with correlated demographics
-            adult2 = _sample_partner_agent(
-                spec,
-                attr_map,
-                rng,
-                agent_index,
-                id_width,
-                stats,
-                numeric_values,
-                adult1,
-                household_attrs,
-                categorical_options,
-            )
-            adult2["household_id"] = household_id
-            adult2["household_role"] = "adult_secondary"
-            # Partners share a surname
-            if adult1.get("last_name"):
-                adult2["last_name"] = adult1["last_name"]
-            adult2["partner_id"] = adult1["_id"]
-            adult1["partner_id"] = adult2["_id"]
-            adult_ids.append(adult2["_id"])
-            agent_index += 1
+        adult2_added = False
+
+        if has_partner:
+            if focus_mode in ("couples", "all") and agent_index < target_n:
+                # Partner is a full agent
+                adult2 = _sample_partner_agent(
+                    spec,
+                    attr_map,
+                    rng,
+                    agent_index,
+                    id_width,
+                    stats,
+                    numeric_values,
+                    adult1,
+                    household_attrs,
+                    categorical_options,
+                )
+                adult2["household_id"] = household_id
+                adult2["household_role"] = "adult_secondary"
+                if adult1.get("last_name"):
+                    adult2["last_name"] = adult1["last_name"]
+                adult2["partner_id"] = adult1["_id"]
+                adult1["partner_id"] = adult2["_id"]
+                adult_ids.append(adult2["_id"])
+                agent_index += 1
+                adult2_added = True
+            else:
+                # Partner is NPC context on the primary agent
+                npc_partner = _generate_npc_partner(
+                    adult1, household_attrs, categorical_options, rng
+                )
+                adult1["partner_npc"] = npc_partner
+                adult1["partner_id"] = None
         else:
             adult1["partner_id"] = None
 
-        # Generate NPC dependents
+        # Dependents
         dependents = generate_dependents(
             htype, household_size, num_adults, adult1_age, rng
         )
-        dep_dicts = [d.model_dump() for d in dependents]
 
-        # Attach dependents to all adults
-        adult1["dependents"] = dep_dicts
+        if has_kids and focus_mode == "all":
+            # Kids become full agents
+            dep_dicts = []
+            for dep in dependents:
+                if agent_index >= target_n:
+                    # Remaining dependents stay as NPC data
+                    dep_dicts.append(dep.model_dump())
+                    continue
+                kid_agent = _sample_dependent_as_agent(
+                    spec,
+                    attr_map,
+                    rng,
+                    agent_index,
+                    id_width,
+                    stats,
+                    numeric_values,
+                    dep,
+                    adult1,
+                    household_id,
+                )
+                agents.append(kid_agent)
+                adult_ids.append(kid_agent["_id"])
+                agent_index += 1
+            # Any overflow dependents attached as NPC data
+            adult1["dependents"] = dep_dicts
+        else:
+            # Kids are NPCs
+            dep_dicts = [d.model_dump() for d in dependents]
+            adult1["dependents"] = dep_dicts
+
         agents.append(adult1)
 
-        if has_partner and len(adult_ids) > 1:
-            adult2["dependents"] = dep_dicts
+        if adult2_added:
+            adult2["dependents"] = adult1.get("dependents", [])
             agents.append(adult2)
 
         # Build household record
@@ -296,7 +435,7 @@ def _sample_population_households(
                 "id": household_id,
                 "household_type": htype.value,
                 "adult_ids": adult_ids,
-                "dependent_data": dep_dicts,
+                "dependent_data": [d.model_dump() for d in dependents],
                 "shared_attributes": shared_attrs,
             }
         )

extropy/population/spec_builder/binder.py

@@ -137,6 +137,7 @@ def bind_constraints(
             type=attr.type,
             category=attr.category,
             description=attr.description,
+            scope=attr.scope,
             sampling=filtered_sampling,
             grounding=attr.grounding,
             constraints=attr.constraints,
@@ -189,6 +190,7 @@ def build_spec(
     attributes: list[AttributeSpec],
     sampling_order: list[str],
     sources: list[str],
+    agent_focus: str | None = None,
 ) -> PopulationSpec:
     """
     Assemble the final PopulationSpec from all components.
@@ -200,6 +202,7 @@ def build_spec(
         attributes: List of AttributeSpec
         sampling_order: Order for sampling
         sources: List of source URLs from research
+        agent_focus: Who the study agents represent (determines agent vs NPC)
 
     Returns:
         Complete PopulationSpec ready for YAML export
@@ -208,6 +211,7 @@ def build_spec(
         description=description,
         size=size,
         geography=geography,
+        agent_focus=agent_focus,
         created_at=datetime.now(),
     )
 

extropy/population/spec_builder/hydrators/conditional.py

@@ -222,6 +222,7 @@ def hydrate_conditional_base(
                 category=original.category,
                 description=original.description,
                 strategy="conditional",
+                scope=original.scope,
                 depends_on=original.depends_on,
                 sampling=sampling,
                 grounding=grounding,
@@ -433,6 +434,7 @@ def hydrate_conditional_modifiers(
                 category=original.category,
                 description=original.description,
                 strategy=original.strategy,
+                scope=original.scope,
                 depends_on=original.depends_on,
                 sampling=new_sampling,
                 grounding=original.grounding,

extropy/population/spec_builder/hydrators/derived.py

@@ -150,6 +150,7 @@ def hydrate_derived(
                 category=original.category,
                 description=original.description,
                 strategy="derived",
+                scope=original.scope,
                 depends_on=original.depends_on,
                 sampling=sampling,
                 grounding=grounding,

extropy/population/spec_builder/hydrators/independent.py

@@ -186,6 +186,7 @@ def hydrate_independent(
                 category=original.category,
                 description=original.description,
                 strategy="independent",
+                scope=original.scope,
                 depends_on=[],
                 sampling=sampling,
                 grounding=grounding,