Nosible

class Nosible(nosible_api_key=None, llm_api_key=None, openai_base_url='https://openrouter.ai/api/v1', sentiment_model='openai/gpt-4o', expansions_model='openai/gpt-4o', timeout=30, retries=5, concurrency=10, publish_start=None, publish_end=None, include_netlocs=None, exclude_netlocs=None, visited_start=None, visited_end=None, certain=None, include_companies=None, exclude_companies=None, include_docs=None, exclude_docs=None, brand_safety=None, language=None, continent=None, region=None, country=None, sector=None, industry_group=None, industry=None, sub_industry=None, iab_tier_1=None, iab_tier_2=None, iab_tier_3=None, iab_tier_4=None, instruction=None, base_url='https://nosible.world/api', http_client=None, *args, **kwargs)

Bases: object

High-level synchronous client for NOSIBLE Search and World.

Search methods

`search`([prompt, agent])	Run agentic Search with Cybernaut.
`fast_search`([search, question, expansions, ...])	Run interactive Fast Search.
`fast_searches`([searches, questions, ...])	Run several Fast searches and return an iterator over results.
`rich_search`(question[, instruction, ...])	Run Rich Search with optional enrichment blocks.
`bulk_search`([search, question, expansions, ...])	Run asynchronous Bulk Search and download its encrypted result archive.
`time_search`(start, end[, frequency, sort, ...])	Run independent searches across a time interval.
`scrape_url`([html, recrawl, render, url])	Scrape a URL or supplied HTML document.
`topic_trend`(query[, start_date, end_date, ...])	Return daily trend values for a topic.
`save_search`(**values)	Save a Search definition.
`get_searches`()	Return saved Searches.
`delete_search`(search_id)	Delete a saved Search.
`get_limits`()	Return Search limits for the current API key.

Convenience methods

`answer`(query[, n_results, min_similarity, ...])	Answer a question using Fast Search results as context.
`generate_expansions`(question)	Generate ten semantically equivalent Search questions.
`format_sql`([publish_start, publish_end, ...])	Build the legacy SQL filter from structured filter values.
`validate_sql`(sql)	Validate Search SQL against the supported engine schema.
`close`()	Close resources owned by this client.

Parameters:

nosible_api_key (str | None)
llm_api_key (str | None)
openai_base_url (str)
sentiment_model (str)
expansions_model (str)
timeout (int)
retries (int)
concurrency (int)
publish_start (str | None)
publish_end (str | None)
include_netlocs (List[str] | None)
exclude_netlocs (List[str] | None)
visited_start (str | None)
visited_end (str | None)
certain (bool | None)
include_companies (List[str] | None)
exclude_companies (List[str] | None)
include_docs (List[str] | None)
exclude_docs (List[str] | None)
brand_safety (str | None)
language (str | None)
continent (str | None)
region (str | None)
country (str | None)
sector (str | None)
industry_group (str | None)
industry (str | None)
sub_industry (str | None)
iab_tier_1 (str | None)
iab_tier_2 (str | None)
iab_tier_3 (str | None)
iab_tier_4 (str | None)
instruction (str | None)
base_url (str)
http_client (Client | None)
args (Any)
kwargs (Any)

search(prompt=None, agent='cybernaut-1')

Run agentic Search with Cybernaut.

Parameters:

prompt (str | None) – Agent instruction from 25 to 2,500 characters.
agent (str) – Agent identifier.
self (Nosible)

Returns:

Agentic search results.

Return type:

ResultSet

fast_searches(searches=None, questions=None, expansions=None, sql_filter=None, n_results=100, n_probes=30, n_contextify=128, algorithm='hybrid-3', min_similarity=None, must_include=None, must_exclude=None, autogenerate_expansions=False, publish_start=None, publish_end=None, include_netlocs=None, exclude_netlocs=None, visited_start=None, visited_end=None, certain=None, include_companies=None, exclude_companies=None, include_docs=None, exclude_docs=None, brand_safety=None, language=None, continent=None, region=None, country=None, sector=None, industry_group=None, industry=None, sub_industry=None, iab_tier_1=None, iab_tier_2=None, iab_tier_3=None, iab_tier_4=None, instruction=None, companies=None, collection=None, deduplicate=None, internal_use=None, **kwargs)

Run several Fast searches and return an iterator over results.

Parameters:

searches (SearchSet | List[Search] | None) – Search objects to execute.
questions (List[str] | None) – Question strings to execute.
expansions (List[str] | None) – Shared query expansions.
sql_filter (str | None) – Shared SQL filter.
n_results (int) – Results requested per search.
n_probes (int) – Search probes per request.
n_contextify (int) – Context size per result.
algorithm (str) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
autogenerate_expansions (bool) – Whether to generate LLM expansions.
publish_start (str | None) – Earliest publication date.
publish_end (str | None) – Latest publication date.
include_netlocs (List[str] | None) – Domains to include.
exclude_netlocs (List[str] | None) – Domains to exclude.
visited_start (str | None) – Earliest visit date.
visited_end (str | None) – Latest visit date.
certain (bool | None) – Whether dates must be certain.
include_companies (List[str] | None) – Company identifiers to include.
exclude_companies (List[str] | None) – Company identifiers to exclude.
include_docs (List[str] | None) – Document hashes to include.
exclude_docs (List[str] | None) – Document hashes to exclude.
brand_safety (str | None) – Brand-safety filter.
language (str | None) – ISO language filter.
continent (str | None) – Continent filter.
region (str | None) – Region filter.
country (str | None) – Country filter.
sector (str | None) – GICS sector filter.
industry_group (str | None) – GICS industry-group filter.
industry (str | None) – GICS industry filter.
sub_industry (str | None) – GICS sub-industry filter.
iab_tier_1 (str | None) – IAB tier-one filter.
iab_tier_2 (str | None) – IAB tier-two filter.
iab_tier_3 (str | None) – IAB tier-three filter.
iab_tier_4 (str | None) – IAB tier-four filter.
instruction (str | None) – Retrieval instruction.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
kwargs (Any) – Deprecated language-list filters.
self (Nosible)

Returns:

Iterator over completed result sets.

Return type:

Iterator[ResultSet]

rich_search(question, instruction=None, expansions=None, sql_filter=None, algorithm='hybrid-3', min_similarity=None, must_include=None, must_exclude=None, brand_safety=None, language=None, continent=None, region=None, country=None, sector=None, industry_group=None, industry=None, sub_industry=None, iab_tier_1=None, iab_tier_2=None, iab_tier_3=None, iab_tier_4=None, companies=None, collection=None, deduplicate=None, internal_use=None, n_results=10, n_probes=30, n_contextify=256, enrich_profile=True, enrich_targeting=True, enrich_history=True, enrich_signals=True, enrich_vectors=True)

Run Rich Search with optional enrichment blocks.

Parameters:

question (str) – Search question.
instruction (str | None) – Retrieval instruction.
expansions (List[str] | None) – Query expansions.
sql_filter (str | None) – SQL filter.
algorithm (str) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
brand_safety (str | None) – Brand-safety filter.
language (str | None) – ISO language filter.
continent (str | None) – Continent filter.
region (str | None) – Region filter.
country (str | None) – Country filter.
sector (str | None) – GICS sector filter.
industry_group (str | None) – GICS industry-group filter.
industry (str | None) – GICS industry filter.
sub_industry (str | None) – GICS sub-industry filter.
iab_tier_1 (str | None) – IAB tier-one filter.
iab_tier_2 (str | None) – IAB tier-two filter.
iab_tier_3 (str | None) – IAB tier-three filter.
iab_tier_4 (str | None) – IAB tier-four filter.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
n_results (int) – Requested result count.
n_probes (int) – Number of search probes.
n_contextify (int) – Context size per result.
enrich_profile (bool) – Whether to return profile enrichment.
enrich_targeting (bool) – Whether to return targeting enrichment.
enrich_history (bool) – Whether to return history enrichment.
enrich_signals (bool) – Whether to return signal enrichment.
enrich_vectors (bool) – Whether to return vector enrichment.
self (Nosible)

Returns:

Rich search results.

Return type:

ResultSet

bulk_search(search=None, question=None, expansions=None, sql_filter=None, n_results=1000, n_probes=10, n_contextify=128, algorithm='hybrid-3', min_similarity=None, must_include=None, must_exclude=None, brand_safety=None, language=None, continent=None, region=None, country=None, sector=None, industry_group=None, industry=None, sub_industry=None, iab_tier_1=None, iab_tier_2=None, iab_tier_3=None, iab_tier_4=None, instruction=None, companies=None, collection=None, deduplicate=None, internal_use=None, poll_interval=15, poll_timeout=1500, verbose=False, autogenerate_expansions=False, publish_start=None, publish_end=None, include_netlocs=None, exclude_netlocs=None, visited_start=None, visited_end=None, certain=None, include_companies=None, exclude_companies=None, include_docs=None, exclude_docs=None, **kwargs)

Run asynchronous Bulk Search and download its encrypted result archive.

Parameters:

search (Search | None) – Optional Search model.
question (str | None) – Search question.
expansions (List[str] | None) – Query expansions.
sql_filter (str | None) – SQL filter.
n_results (int) – Requested result count.
n_probes (int) – Number of search probes.
n_contextify (int) – Context size per result.
algorithm (str) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
brand_safety (str | None) – Brand-safety filter.
language (str | None) – ISO language filter.
continent (str | None) – Continent filter.
region (str | None) – Region filter.
country (str | None) – Country filter.
sector (str | None) – GICS sector filter.
industry_group (str | None) – GICS industry-group filter.
industry (str | None) – GICS industry filter.
sub_industry (str | None) – GICS sub-industry filter.
iab_tier_1 (str | None) – IAB tier-one filter.
iab_tier_2 (str | None) – IAB tier-two filter.
iab_tier_3 (str | None) – IAB tier-three filter.
iab_tier_4 (str | None) – IAB tier-four filter.
instruction (str | None) – Retrieval instruction.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
poll_interval (float) – Download polling interval in seconds.
poll_timeout (float) – Maximum polling duration in seconds.
verbose (bool) – Retained compatibility flag.
autogenerate_expansions (bool) – Whether to generate LLM expansions.
publish_start (str | None) – Earliest publication date.
publish_end (str | None) – Latest publication date.
include_netlocs (List[str] | None) – Domains to include.
exclude_netlocs (List[str] | None) – Domains to exclude.
visited_start (str | None) – Earliest visit date.
visited_end (str | None) – Latest visit date.
certain (bool | None) – Whether dates must be certain.
include_companies (List[str] | None) – Company identifiers to include.
exclude_companies (List[str] | None) – Company identifiers to exclude.
include_docs (List[str] | None) – Document hashes to include.
exclude_docs (List[str] | None) – Document hashes to exclude.
kwargs (Any) – Deprecated language-list filters.
self (Nosible)

Returns:

Downloaded bulk results.

Return type:

ResultSet

time_search(start, end, frequency='1d', sort='ascending', require_timezone=False, n_results=25, n_probes=10, n_contextify=128, question=None, instruction=None, expansions=None, sql_filter=None, algorithm=None, min_similarity=None, must_include=None, must_exclude=None, companies=None, collection=None, deduplicate=None, internal_use=None, poll_interval=15, poll_timeout=1500, **filters)

Run independent searches across a time interval.

Parameters:

start (str) – Inclusive timezone-aware ISO start timestamp.
end (str) – Exclusive timezone-aware ISO end timestamp.
frequency (str) – Positive h, d, w, or mo interval.
sort (str) – Result order, ascending or descending.
require_timezone (bool) – Whether results must expose timezone data.
n_results (int) – Results requested per interval.
n_probes (int) – Number of search probes.
n_contextify (int) – Context size per result.
question (str | None) – Optional Search question.
instruction (str | None) – Retrieval instruction.
expansions (List[str] | None) – Query expansions.
sql_filter (str | None) – SQL filter.
algorithm (str | None) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
poll_interval (float) – Download polling interval in seconds.
poll_timeout (float) – Maximum polling duration in seconds.
filters (Any) – Additional inherited Search filters.
self (Nosible)

Returns:

Downloaded time-search response.

Return type:

Dict[str, Any]

scrape_url(html='', recrawl=False, render=False, url=None)

Scrape a URL or supplied HTML document.

Parameters:

html (str) – Optional raw HTML.
recrawl (bool) – Whether to force a fresh crawl.
render (bool) – Whether to render JavaScript.
url (str | None) – URL to scrape.
self (Nosible)

Returns:

Structured web-page data.

Return type:

WebPageData

topic_trend(query, start_date=None, end_date=None, sql_filter=None)

Return daily trend values for a topic.

Parameters:

query (str) – Topic query from 5 to 100 characters.
start_date (str | None) – Optional inclusive first date.
end_date (str | None) – Optional inclusive final date.
sql_filter (str | None) – Optional Search SQL filter.
self (Nosible)

Returns:

Date-keyed trend values.

Return type:

Dict[str, Any]

save_search(**values)

Save a Search definition.

Parameters:

values (Any) – Saved Search fields.
self (Nosible)

Returns:

Saved Search response.

Return type:

Dict[str, Any]

get_searches()

Return saved Searches.

Returns:: Saved Search response.
Parameters:: self (Nosible)
Return type:: Dict[str, Any]

delete_search(search_id)

Delete a saved Search.

Parameters:

search_id (str) – Saved Search identifier.
self (Nosible)

Returns:

Deletion response.

Return type:

Dict[str, Any]

get_limits()

Return Search limits for the current API key.

Returns:: Search limit response.
Parameters:: self (Nosible)
Return type:: Dict[str, Any]

answer(query, n_results=100, min_similarity=0.65, model='google/gemini-2.0-flash-001', show_context=True)

Answer a question using Fast Search results as context.

Parameters:

query (str) – Natural-language question.
n_results (int) – Results used as context.
min_similarity (float) – Minimum context similarity.
model (str | None) – OpenAI-compatible model name.
show_context (bool) – Whether to print the assembled context.
self (Nosible)

Returns:

LLM answer.

Return type:

str

fast_search(search=None, question=None, expansions=None, sql_filter=None, n_results=100, n_probes=30, n_contextify=128, algorithm='hybrid-3', min_similarity=None, must_include=None, must_exclude=None, autogenerate_expansions=False, publish_start=None, publish_end=None, include_netlocs=None, exclude_netlocs=None, visited_start=None, visited_end=None, certain=None, include_companies=None, exclude_companies=None, include_docs=None, exclude_docs=None, brand_safety=None, language=None, continent=None, region=None, country=None, sector=None, industry_group=None, industry=None, sub_industry=None, iab_tier_1=None, iab_tier_2=None, iab_tier_3=None, iab_tier_4=None, instruction=None, companies=None, collection=None, deduplicate=None, internal_use=None, *args, **kwargs)

Run interactive Fast Search.

Parameters:

search (Search | None) – Optional Search model.
question (str | None) – Search question.
expansions (List[str] | None) – Query expansions.
sql_filter (str | None) – SQL filter.
n_results (int) – Requested result count.
n_probes (int) – Number of search probes.
n_contextify (int) – Context size per result.
algorithm (str) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
autogenerate_expansions (bool) – Whether to generate LLM expansions.
publish_start (str | None) – Earliest publication date.
publish_end (str | None) – Latest publication date.
include_netlocs (List[str] | None) – Domains to include.
exclude_netlocs (List[str] | None) – Domains to exclude.
visited_start (str | None) – Earliest visit date.
visited_end (str | None) – Latest visit date.
certain (bool | None) – Whether dates must be certain.
include_companies (List[str] | None) – Company identifiers to include.
exclude_companies (List[str] | None) – Company identifiers to exclude.
include_docs (List[str] | None) – Document hashes to include.
exclude_docs (List[str] | None) – Document hashes to exclude.
brand_safety (str | None) – Brand-safety filter.
language (str | None) – ISO language filter.
continent (str | None) – Continent filter.
region (str | None) – Region filter.
country (str | None) – Country filter.
sector (str | None) – GICS sector filter.
industry_group (str | None) – GICS industry-group filter.
industry (str | None) – GICS industry filter.
sub_industry (str | None) – GICS sub-industry filter.
iab_tier_1 (str | None) – IAB tier-one filter.
iab_tier_2 (str | None) – IAB tier-two filter.
iab_tier_3 (str | None) – IAB tier-three filter.
iab_tier_4 (str | None) – IAB tier-four filter.
instruction (str | None) – Retrieval instruction.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
args (Any) – Ignored legacy positional arguments.
kwargs (Any) – Deprecated language-list filters.
self (Nosible)

Returns:

Interactive search results.

Return type:

ResultSet

close()

Close resources owned by this client.

Returns:: None.
Parameters:: self (Nosible)
Return type:: None

search_payload(search, question, instruction, expansions, sql_filter, algorithm, min_similarity, must_include, must_exclude, brand_safety, language, continent, region, country, sector, industry_group, industry, sub_industry, iab_tier_1, iab_tier_2, iab_tier_3, iab_tier_4, companies, collection, deduplicate, internal_use, n_results, n_probes, n_contextify, autogenerate_expansions, legacy_filters)

Merge direct, model, generated, and legacy Search fields.

Parameters:

search (Search | None) – Optional Search model.
question (str | None) – Direct Search question.
instruction (str | None) – Retrieval instruction.
expansions (List[str] | None) – Query expansions.
sql_filter (str | None) – SQL filter.
algorithm (str | None) – Retrieval algorithm.
min_similarity (float | None) – Minimum similarity score.
must_include (List[str] | None) – Required strings.
must_exclude (List[str] | None) – Forbidden strings.
brand_safety (str | None) – Brand-safety filter.
language (str | None) – ISO language filter.
continent (str | None) – Continent filter.
region (str | None) – Region filter.
country (str | None) – Country filter.
sector (str | None) – GICS sector filter.
industry_group (str | None) – GICS industry-group filter.
industry (str | None) – GICS industry filter.
sub_industry (str | None) – GICS sub-industry filter.
iab_tier_1 (str | None) – IAB tier-one filter.
iab_tier_2 (str | None) – IAB tier-two filter.
iab_tier_3 (str | None) – IAB tier-three filter.
iab_tier_4 (str | None) – IAB tier-four filter.
companies (List[str] | None) – Company names to refine retrieval.
collection (str | None) – Search collection.
deduplicate (bool | None) – Whether to remove duplicate headlines.
internal_use (Dict[str, Any] | None) – Private feature controls.
n_results (int | None) – Requested result count.
n_probes (int | None) – Number of search probes.
n_contextify (int | None) – Context size per result.
autogenerate_expansions (bool) – Whether to generate expansions.
legacy_filters (Dict[str, Any]) – Structured legacy filters.
self (Nosible)

Returns:

Search API request payload.

Return type:

Dict[str, Any]

generate_expansions(question)

Generate ten semantically equivalent Search questions.

Parameters:

question (str | Search) – Source question or Search model.
self (Nosible)

Returns:

Ten generated query expansions.

Return type:

List[str]

format_sql(publish_start=None, publish_end=None, visited_start=None, visited_end=None, certain=None, include_netlocs=None, exclude_netlocs=None, include_companies=None, exclude_companies=None, include_docs=None, exclude_docs=None)

Build the legacy SQL filter from structured filter values.

Parameters:

publish_start (str | None) – Earliest publication date.
publish_end (str | None) – Latest publication date.
visited_start (str | None) – Earliest visit date.
visited_end (str | None) – Latest visit date.
certain (bool | None) – Whether dates must be certain.
include_netlocs (List[str] | None) – Domains to include.
exclude_netlocs (List[str] | None) – Domains to exclude.
include_companies (List[str] | None) – Company identifiers to include.
exclude_companies (List[str] | None) – Company identifiers to exclude.
include_docs (List[str] | None) – Document hashes to include.
exclude_docs (List[str] | None) – Document hashes to exclude.
self (Nosible)

Returns:

Valid Search SQL filter.

Return type:

str

validate_sql(sql)

Validate Search SQL against the supported engine schema.

Parameters:

sql (str) – SQL query to validate.
self (Nosible)

Returns:

Whether Polars accepts the SQL against the engine schema.

Return type:

bool

downloaded_search(endpoint, payload, poll_interval, poll_timeout)

Poll and decode an encrypted Search download.

Parameters:

endpoint (str) – Bulk or Time Search endpoint suffix.
payload (Dict[str, Any]) – Search request body.
poll_interval (float) – Polling interval in seconds.
poll_timeout (float) – Maximum polling duration in seconds.
self (Nosible)

Returns:

Decoded Search response.

Return type:

Dict[str, Any]

search_json(endpoint, payload)

Post to a Search v2.1 endpoint and require an object response.

Parameters:

endpoint (str) – Search endpoint suffix.
payload (Dict[str, Any]) – JSON request body.
self (Nosible)

Returns:

JSON response object.

Return type:

Dict[str, Any]