Skip to main content
Scope your territory before you chase anything. Which entities and themes actually matter to your question is rarely obvious up front, and pinning it down by hand means days of reading around to learn who is moving and where the conversation sits. Gildea makes it a few calls. A live theme map shows the market’s structure and its momentum, faceted entity navigation surfaces who is rising and who is fading, and a full profile on any entity anchors your scope to real, tracked data. The output is your territory: the themes and entities every later step searches, monitors, and verifies against.

​
The recipe

Scoping is pure navigation over Gildea’s structured layer, with no model calls. You read the theme map, facet the entity space down to the ones you care about, profile your central entity, then lock the result into a scope the other recipes reuse.
1

Map the market

Pull the theme vocabulary. Themes sit on two axes: value_chain (the structural layers, from infrastructure up to applications) and market_force (the dynamics acting on them). Each carries weekly momentum, so you see what is heating up and what is cooling. See Themes.
2

Facet the entities

entities.list exposes nine facets (type, theme, scale, direction, confidence, stability, notability, name) plus sort. Slice the entity space down to your territory, and contrast who is rising against who is declining. See Entities.
3

Profile your central entity

entities.get returns the full picture for one entity: its trend and reach, where it operates across the value chain, the market forces touching it, and the entities it is most discussed alongside.
4

Lock the scope

Combine the themes, entities, and a time window into the territory every later recipe operates over.
Install gildea, set GILDEA_API_KEY, then (pure SDK, no model calls): 
from gildea import Gildea

gildea = Gildea()

# 1. The market map: themes sit on two axes -- value_chain (structural layers,
#    infra -> apps) and market_force (the dynamics on them). Each carries momentum.
themes = gildea.themes.list()["themes"]

def by_axis(axis):
    rows = [t for t in themes if t["axis"] == axis]
    return sorted(rows, key=lambda t: t["signal_count"], reverse=True)

for axis in ("value_chain", "market_force"):
    print(f"\n{axis}:")
    for t in by_axis(axis):
        delta = t["trend"]["current_week"] - t["trend"]["prior_week"]
        print(f"  {t['label']:26} {t['signal_count']:>4} signals  "
              f"{t['direction'] or '-':9} wk {delta:+d}")

# Anchor your territory on the busiest structural theme.
theme = by_axis("value_chain")[0]["label"]

# 2. Faceted entity navigation: nine facets + sort. Contrast two slices.
def orgs(theme, **facets):
    return gildea.entities.list(
        theme=theme, type="organization", sort="trend", limit=50, **facets
    )["entities"]

rising = orgs(theme, direction="Rising")
declining = orgs(theme, direction="Declining", notability="High")
print(f"\nIn '{theme}': {len(rising)} rising / {len(orgs(theme))} total orgs")
print("  rising:   ", ", ".join(e["name"] for e in rising[:6]) or "(none this week)")
print("  declining:", ", ".join(e["name"] for e in declining[:6]))

# 3. Central entity profile: the full intelligence picture for one entity.
e = gildea.entities.get("NVIDIA")
tr = e["trend"]
print(f"\n{e['name']} ({e['entity_id']}) -- {e['type']}, scale={e['scale']}, "
      f"{e['direction']}, notability={e['notability']}")
print(f"  reach: share_of_voice={tr['share_of_voice']:.0%}, "
      f"{tr['source_diversity']} distinct sources, wk {tr['current_week']} vs {tr['prior_week']}")

def top(dist, n=3):
    return ", ".join(f"{k} ({v})" for k, v in sorted(dist.items(), key=lambda x: -x[1])[:n])

print(f"  operates in: {top(e['value_chain_distribution'])}")
print(f"  forces:      {top(e['market_force_distribution'])}")
mix = e["content_type_mix"]
print(f"  coverage:    {mix.get('event', 0)} events / {mix.get('analysis', 0)} analyses")
print(f"  alongside:   {', '.join(r['name'] for r in e['related_entities'][:6])}")

# 4. Lock the scope: themes + entities + window = the territory every later
#    recipe (search, update, verify, embed) operates over.
scope = {
    "themes": [theme],
    "entities": [e["entity_id"]] + [r["entity_id"] for r in e["related_entities"][:5]],
    "window": "90d",
}
print(f"\nscope locked: {len(scope['entities'])} entities, theme '{theme}', window {scope['window']}")

​
What you get

Your territory: the themes that frame the question, the entities worth tracking within them, and a profile of your central entity, every field from real tracked data. It is a plain object the rest of the loop reuses. Search pulls verified signals across it, Update keeps it current, Verify traces any unit back to its source, and Embed stores it beside your own data. Because scope is built from live theme and entity intelligence, re-running it re-checks who is moving before you commit.

List themes

Get entity

Search for signals