emergingtrajectories ==================== .. py:module:: emergingtrajectories Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/emergingtrajectories/agents/index /autoapi/emergingtrajectories/chunkers/index /autoapi/emergingtrajectories/citationagents/index /autoapi/emergingtrajectories/crawlers/index /autoapi/emergingtrajectories/facts/index /autoapi/emergingtrajectories/factsforecaster/index /autoapi/emergingtrajectories/factsrag/index /autoapi/emergingtrajectories/factsrag2/index /autoapi/emergingtrajectories/factsrag3/index /autoapi/emergingtrajectories/factsragforecaster/index /autoapi/emergingtrajectories/factsragforecaster2/index /autoapi/emergingtrajectories/factsragforecaster3/index /autoapi/emergingtrajectories/knowledge/index /autoapi/emergingtrajectories/news/index /autoapi/emergingtrajectories/pdf/index /autoapi/emergingtrajectories/prompts/index /autoapi/emergingtrajectories/recursiveagent/index /autoapi/emergingtrajectories/utils/index Classes ------- .. autoapisummary:: emergingtrajectories.Statement emergingtrajectories.Forecast emergingtrajectories.Client emergingtrajectories.EmergingTrajectoriesClient Functions --------- .. autoapisummary:: emergingtrajectories.hello Package Contents ---------------- .. py:function:: hello() -> None Just a hello() message/function to confirm you've installed everything! .. py:class:: Statement(title, fill_in_the_blank) Bases: :py:obj:`object` .. py:attribute:: id :value: -1 .. py:attribute:: title .. py:attribute:: fill_in_the_blank .. py:attribute:: description :value: '' .. py:attribute:: deadline :value: None .. py:attribute:: created_at :value: None .. py:attribute:: updated_at :value: None .. py:attribute:: created_by :value: None .. py:class:: Forecast(title, value, justification) Bases: :py:obj:`object` .. py:attribute:: id :value: -1 .. py:attribute:: title .. py:attribute:: value .. py:attribute:: justification .. py:attribute:: statement :value: None .. py:attribute:: created_at :value: None .. py:attribute:: updated_at :value: None .. py:attribute:: created_by :value: None .. py:attribute:: prediction_agent :value: None .. py:attribute:: additional_data .. py:attribute:: prior_forecast :value: None .. py:attribute:: next_forecasts :value: [] .. py:attribute:: is_human :value: False .. py:class:: Client(api_key: str) Bases: :py:obj:`object` Launch the Emerging Trajectories Client. :param api_key: the API key for the Emerging Trajectories platform. .. py:attribute:: base_url :value: 'https://app.emergingtrajectories.com/a/api/v0.2/' .. py:attribute:: api_key .. py:method:: create_statement(title: str, description: str, deadline: datetime.datetime, fill_in_the_blank: str) -> dict Create a new statement that users will be forecasting against/for. :param title: the title of the statement :param description: a more detailed description of the statement :param deadline: the deadline (date and time), typically when we'll learn the "right answer" for the forecasting process :param fill_in_the_blank: the "fill in the blank" part of the statement, which is what users will be forecasting against :returns: the newly created statement returned from the platform :rtype: dict .. py:method:: get_statement(statement_id: int) -> dict Returns a given statement from the platform. Includes title, description, deadline, and fill-in-the-blank. :param statement_id: the ID of the statement to retrieve :returns: the statement from the platform :rtype: dict .. py:method:: get_most_recent_forecast(statement_id: int, prediction_agent: str = None) -> int Returns the most recent forecast for a given statement. This is useful for creating a new forecast that is an extension of a prior forecast. :param statement_id: the ID of the statement to retrieve the most recent forecast for :param prediction_agent: the string for a prediction agent, if you want to further filter the most recent forecast :returns: the ID of the most recent forecast for the given statement :rtype: int .. py:method:: get_forecast(forecast_id: int) -> dict Returns a specific forecast's details from the platform. This typically includes the forecast title, the value associated with the fill-in-the-blank component of a statement, and justificaiton for the forecast. :param forecast_id: the ID of the forecast to retrieve :returns: the forecast details in the form of a dictionary object :rtype: dict .. py:method:: create_forecast(statement_id: int, title: str, justification: str, value: float, prediction_agent: str, additional_data: dict = {}, prior_forecast: int = None, is_human: bool = False) -> None Creates a forecast tied to a specific statement. :param statement_id: the ID of the statement to tie the forecast to :param title: the title of the forecast :param justification: the justification for the forecast :param value: the value associated with the fill-in-the-blank component of the statement :param prediction_agent: the agent making the prediction :param additional_data: any additional data to include with the forecast. This is not used anywhere, but can be helpful in audting or researching forecast effectiveness :param prior_forecast: if this forecast is an extension of an earlier forecast, the ID of the prior forecast :param is_human: whether the prediction is human-generated :returns: the newly created forecast from the platform :rtype: dict .. py:class:: EmergingTrajectoriesClient(api_key: str) Bases: :py:obj:`object` :param api_key: the API key for the Emerging Trajectories platform. .. py:attribute:: base_url :value: 'https://app.emergingtrajectories.com/a/api/v0.2/' .. py:attribute:: api_key .. py:method:: get_events(project_codes: Union[str, List[str]] = None, limit: int = 100) -> List[dict] Get events from the Emerging Trajectories platform. :param project_codes: a single project code or a list of project codes to filter events by :returns: a list of events, each represented as a dictionary :rtype: List[dict] .. py:method:: search_public_events(query, project_codes: Union[str, List[str]], limit: int = 10) -> List[dict] Search for public events on the Emerging Trajectories platform. :param query: the search query string :param project_codes: a single project code or a list of project codes to filter events by :param limit: the maximum number of events to return :returns: a list of events, each represented as a dictionary :rtype: List[dict] .. py:method:: upload_pdf(pdf_path: str, factbase_shortcode: str) -> bool Upload a PDF to the Emerging Trajectories platform. :param pdf_path: the path to the PDF file to upload :param factbase_shortcode: the short code for the factbase to attach the PDF to :returns: returns True if file has been uploaded successfully :rtype: bool .. py:method:: create_factbase(title: str, description: str) -> str Create a new factbase on the Emerging Trajectories platform. :param title: the title of the factbase :param description: a description of the factbase :returns: The short_code for the factbase. :rtype: str .. py:method:: get_facts(short_code, query, days_filter=1, pubdate_days_filter=-1, use_text_match=False) -> str Query the fact base and simply get the raw facts normally generated for documents or other internal processes. :param short_code: the short code for the factbase to query :param query: the query to run :param days_filter: limit facts to the recent number of days :param pubdate_days_filter: limit facts to the recent number of days based on publication date :param use_text_match: use text matching for the query :returns: A list of facts as a string. :rtype: str .. py:method:: query_factbase(short_code, query, days_filter=1, pubdate_days_filter=-1, llm_model=None, llm_temperature=None) -> str Query the fact base as if you'd query a document, but with no document required. The responses here are ephemeral and are not stored anywhere. :param short_code: the short code for the factbase to query :param query: the query to run :param days_filter: limit facts to the recent number of days :param pubdate_days_filter: limit facts to the recent number of days based on publication date :param llm_model: the LLM model to use :param llm_temperature: the LLM temperature to use :returns: The response written based on facts in the fact base. :rtype: str .. py:method:: build_research_plan(query: str) -> dict Given a research question/query, we create a set of tasks that we can then automate document creation around. :param query: the research question/query to build tasks around :returns: a dictionary with two keys -- "text" which is the text plan, and "plan" which is a JSON plan :rtype: dict .. py:method:: run_research_sub_task(command: str, args: Union[str, List[str]], document_id: int, short_code: str, wait_until_completion: bool = True) -> int Run the research sub-task outlined in a research plan. :param command: the command to run :param args: the arguments to pass to the command :param document_id: the ID of the document to attach the research task to :param short_code: the short code for the factbase to use :param wait_until_completion: whether to wait until the task is completed before returning :returns: the ID of the job or -1 if not applicable :rtype: int .. py:method:: research_task_header_and_block(doc_id: int, query: str) -> int Runs a research analyst task where we generate a header block and then run the query for the document. :param doc_id: the ID of the document to attach the research task to :param query: the query to run :returns: the ID of the job :rtype: int .. py:method:: run_data_collector_job(factbase_shortcode: str, settings: dict) -> int Creates a new data collector job and runs it. Contact us for information on how to pass settings. :param factbase_shortcode: the short code for the factbase :param settings: a dictionary of settings for the data collector job :returns: The ID of the job :rtype: int .. py:method:: run_data_collector_serp(factbase_shortcode: str, query: Union[str, List[str]], n: int = 5, settings: dict = None) -> int Creates a new data collector job and runs it. Contact us for information on how to pass settings. :param factbase_shortcode: the short code for the factbase :param query: a string to search or an array of strings :param settings: a dictionary of settings for the data collector job :returns: The ID of the job :rtype: int .. py:method:: run_data_collector_news(factbase_shortcode: str, query: Union[str, List[str]], n: int = 5, settings: dict = None) -> int Creates a new data collector job and runs it. Contact us for information on how to pass settings. :param factbase_shortcode: the short code for the factbase :param query: a string to search or an array of strings :param settings: a dictionary of settings for the data collector job :returns: The ID of the job :rtype: int .. py:method:: get_data_collector_job_status(job_id: int) -> str Get the status of a data collector job. :param job_id: the ID of the job :returns: The status of the job :rtype: str .. py:method:: create_document(factbase_shortcode: str, title: str = None, days_filter=99999, temperature=None, llm=None, facts_min_date=None, facts_max_date=None) -> int Create a new document on the Emerging Trajectories platform. :param factbase_shortcode: the short code for the factbase to attach the document to :param title: the title of the document :type title: optional :param days_filter: limit facts to the recent number of days :type days_filter: optional :returns: The ID of the document. :rtype: int .. py:method:: convert_facts_in_text(factbase_shortcode: str, text: str) Convert text with facts to HTML code with associated links. :param factbase_shortcode: the short code for the factbase to attach the document to :param text: the text to convert :returns: the converted text as HTML array: a list facts found in the text, with the key being the source ID in the HTML :rtype: str .. py:method:: update_document(doc_id: int, title: str = None, is_public: bool = None, short_code: str = None) -> bool Update document settings. :param doc_id: the ID of the document :param title: the new title of the document :param is_public: whether the document is public (updated setting) :param short_code: the short code for the document (updated setting) :returns: True if successful, False otherwise :rtype: bool .. py:method:: get_document(doc_id: int) -> dict Get document data. :param doc_id: the ID of the document :returns: The ID of the document. :rtype: int .. py:method:: add_viewer(doc_id: int, viewer_email: str) -> bool Add a viewer to a private document. :param doc_id: the ID of the document :param viewer_email: the email of the viewer to add :returns: True if successful, False otherwise :rtype: bool .. py:method:: remove_viewer(doc_id: int, viewer_email: str) -> bool Remove a viewer from a private document. :param doc_id: the ID of the document :param viewer_email: the email of the viewer to remove :returns: True if successful or if the email is NOT a viewer already, False otherwise :rtype: bool .. py:method:: get_block(doc_id: int, block_named_id: str) -> str Get the content of a named block from a document. :param doc_id: the ID of the document :param block_named_id: the named ID of the block to retrieve :returns: the content of the block :rtype: str .. py:method:: append_header_block(doc_id, text: str, is_hidden: bool = False) -> bool Add a header block to a document. :param doc_id: the ID of the document to append the header block to :param text: the text (header) to append :param is_hidden: whether the block is hidden in public documents :returns: True if successful, False otherwise :rtype: bool .. py:method:: append_text_block(doc_id: int, text: str) -> bool Add a text block to a document. :param doc_id: the ID of the document to append the text block to :param text: the text to append :returns: True if successful, False otherwise :rtype: bool .. py:method:: append_hidden_block(doc_id: int, prompt: str) -> bool Add a text block to a document. :param doc_id: the ID of the document to append the text block to :param prompt: the text (typically a prompt) to append :returns: True if successful, False otherwise :rtype: bool .. py:method:: append_askai_fts_block(doc_id: int, query: str, fts_term: str, named_id: str = None, is_hidden: bool = False) -> dict Add an AI (FTS) block to a document. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param fts_term: the full text search (FTS) terms/query to use for the AI block :param named_id: the named ID of the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_risk_score_doc_block(doc_id: int, query: str, named_id: str = None, is_hidden: bool = False) -> dict Add a risk score block to a document. This risk score only evaluates based on what's in the document already; it does not query the fact base. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param named_id: the named ID of the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_askai_fts_cot_block(doc_id: int, query: str, fts_term: str, named_id: str = None, is_hidden: bool = False) -> dict Add an AI (FTS) block to a document. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param fts_term: the full text search (FTS) terms/query to use for the AI block :param named_id: the named ID of the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_askai_cot_block(doc_id: int, query: str, named_id: str = None, is_hidden: bool = False) -> dict Add an AI (COT) block to a document. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param named_id: the named ID of the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_askai_cot_pubdate_block(doc_id: int, query: str, named_id: str = None, is_hidden: bool = False) -> dict Add an AI (COT) block to a document. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param named_id: the named ID of the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_askai_block(doc_id: int, query: str, named_id: str = None, is_hidden: bool = False) -> dict Add an AI block to a document. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param is_hidden: whether the block is hidden in public documents :returns: JSON dict with document information .. py:method:: append_askai_block_fact_range(doc_id: int, query: str, named_id: str = None, is_hidden: bool = False, num_results=10, num_before=7, num_after=7) -> dict Add an AI 'fact range' block to a document. This uses an experimental form of RAG that should reduce hallucinations but also reduces the # of sources that can be queried. :param doc_id: the ID of the document to append the text block to :param query: the query to use for the AI block :param is_hidden: whether the block is hidden in public documents :param num_results: the number of results (sources) to return when doing a deep dive :param num_before: the number of facts to include prior to the core fact (with chunking) :param num_after: the number of facts to include after the core fact (with chunking) :returns: JSON dict with document information .. py:method:: create_automation_factbase(short_code, job_type, arg_string=None, args=None) Create an automation for a fact base. :param short_code: the short code for the factbase :param job_type: the type of job to run :param arg_string: a string of arguments :param args: a dictionary of arguments if the job requires more than one :returns: the automation object :rtype: dict .. py:method:: create_automation_document(doc_id, job_type, arg_string=None, args=None) Create an automation for a document. :param doc_id: the document ID :param job_type: the type of job to run :param arg_string: a string of arguments :param args: a dictionary of arguments if the job requires more than one :returns: the automation object :rtype: dict .. py:method:: get_factbase_automations(factbase_short_code) Get an array of all automations that can be run on a factbase. :param factbase_short_code: the short code for the factbase :returns: an array of automations that can be run on the factbase :rtype: list .. py:method:: queue_automation(automation_id) Queue an automation (i.e., request the Emerging Trajectories platform to run an automation). :param automation_id: the ID of the automation to queue :returns: True if successful, False otherwise :rtype: bool .. py:method:: get_statement(statement_id: int) -> Statement Returns a given statement from the platform. Includes title, description, deadline, and fill-in-the-blank. :param statement_id: the ID of the statement to retrieve :returns: the statement from the platform :rtype: Statement .. py:method:: get_forecast(forecast_id: int) -> Forecast Returns a given forecast from the platform. :param forecast_id: the ID of the statement to retrieve :returns: the forecast from the platform :rtype: Forecast .. py:method:: get_facts_from_factbase(fact_db_slug: str, fact_id: str = None, fact_ids: list = None, source_url: str = None) -> list[dict] Gets a list of facts from a fact base. :param fact_db_slug: the slug of the fact database to get facts from. :param fact_id: the ID of the fact to retrieve. :param fact_ids: a list of fact IDs to retrieve. :param source_url: the URL of the source to retrieve facts from. :returns: a list of facts from the fact base. :rtype: list .. py:method:: add_facts_to_factbase(fact_db_slug: str, url: str, facts: list[str]) -> bool Adds a list of facts to a factbase on the Emerging Trajectories website. :param fact_db_slug: the slug of the fact database to add the fact to. :param url: the URL of the fact. :param facts: the facts to add (a list of strings). :returns: True if successful, False otherwise. :rtype: bool .. py:method:: add_facts_to_factbase_unique_urls(fact_db_slug: str, urls: list[str], facts: list[str], pubdates: list[datetime.datetime] = None) -> bool Adds a list of facts to a factbase on the Emerging Trajectories website. This currently has a maximum # of 100 facts that can be sent at a time. :param fact_db_slug: the slug of the fact database to add the fact to. :param urls: the URLs of the facts. :param facts: the facts to add (a list of strings). :param pubdates: the publication dates of the facts. :returns: True if successful, False otherwise. :rtype: bool .. py:method:: add_fact_to_factbase(fact_db_slug: str, url: str, fact: str, pubdate=None) -> bool Adds a fact to a factbase on the Emerging Trajectories website. :param fact_db_slug: the slug of the fact database to add the fact to. :param url: the URL of the fact. :param fact: the fact to add. :param pubdate: datetime object for when the fact was published. :returns: True if successful, False otherwise. :rtype: bool .. py:method:: add_content_to_factbase(fact_db_slug: str, url: str, content: str, topic: str) -> bool Sends content to the Emerging Trajectories website and extract facts from it. :param fact_db_slug: the slug of the fact database to add the content to. :param url: the URL of the content. Note: we do not actually crawl this, we assume the content passed is the right conent. :param content: the content to extract facts from. :param topic: the topic of the content. :returns: True if successful, False otherwise. :rtype: bool .. py:method:: add_url_to_factbase(fact_db_slug: str, url: Union[str, list[str]], topic: str = '') -> bool Sends URL to the Emerging Trajectories website, crawls the URL, and extracts facts from it. :param fact_db_slug: the slug of the fact database to add the content to. :param url: the URL of the content, which we will crawl. Could also be an array. :param topic: the topic of the content. :returns: True if successful, False otherwise. :rtype: bool