forecasting-tools 0.2.92__tar.gz → 0.3.0__tar.gz

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forecasting-tools
-Version: 0.2.92
+Version: 0.3.0
 Summary: AI forecasting and research tools to help humans reason about and forecast the future
 License: MIT
 License-File: LICENSE
@@ -19,31 +19,42 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Provides-Extra: agents
+Provides-Extra: all
+Provides-Extra: front-end
+Provides-Extra: source-archive
+Provides-Extra: stats
 Requires-Dist: aiofiles (>=24.1.0,<26.0.0)
 Requires-Dist: aiohttp (>=3.9.3,<4.0.0)
 Requires-Dist: aiolimiter (>=1.1.0,<2.0.0)
-Requires-Dist: asknews (>=0.9.1,<0.14.0)
+Requires-Dist: asknews (>=0.9.1,<0.15.0)
 Requires-Dist: asyncio (>=3.0.0,<5.0.0)
+Requires-Dist: boto3 (>=1.34,<2.0.0) ; extra == "source-archive" or extra == "all"
+Requires-Dist: cloakbrowser (>=0.3.31,<0.4.0) ; extra == "source-archive" or extra == "all"
 Requires-Dist: exceptiongroup (>=1.2.2,<2.0.0)
-Requires-Dist: faker (>=37.0.0,<41.0.0)
-Requires-Dist: hyperbrowser (>=0.53.0,<1.0.0)
+Requires-Dist: faker (>=37.0.0,<41.0.0) ; extra == "agents" or extra == "front-end" or extra == "all"
+Requires-Dist: firecrawl-py (>=4.0,<5.0.0) ; extra == "source-archive" or extra == "all"
+Requires-Dist: hyperbrowser (>=0.53.0,<2.0.0) ; extra == "source-archive" or extra == "agents" or extra == "front-end" or extra == "all"
 Requires-Dist: litellm (>=1.59.1,<2.0.0,!=1.76.*,!=1.77.*,!=1.82.7,!=1.82.8)
 Requires-Dist: nest-asyncio (>=1.5.8,<2.0.0)
 Requires-Dist: numpy (>=1.26.0,<3.0.0)
-Requires-Dist: openai (>=1.51.0,<3.0.0)
-Requires-Dist: openai-agents[litellm] (>=0.2.0,<0.20.0)
-Requires-Dist: pandas (>=2.2.3,<4.0.0)
+Requires-Dist: openai (>=1.51.0,<4.0.0)
+Requires-Dist: openai-agents[litellm] (>=0.2.0,<0.23.0) ; extra == "agents" or extra == "front-end" or extra == "all"
+Requires-Dist: pandas (>=2.2.3,<4.0.0) ; extra == "front-end" or extra == "stats" or extra == "all"
 Requires-Dist: pendulum (>=3.1.0,<4.0.0)
 Requires-Dist: pillow (>=9.0.0,<13.0.0)
-Requires-Dist: plotly (>=5.24.1,<7.0.0)
+Requires-Dist: playwright (>=1.44,<2.0.0) ; extra == "source-archive" or extra == "all"
+Requires-Dist: plotly (>=5.24.1,<8.0.0) ; extra == "front-end" or extra == "all"
 Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: pymupdf4llm (>=0.0.17,<1.0.0) ; extra == "source-archive" or extra == "all"
 Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
-Requires-Dist: regex (>=2024.11.6,<2027.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
-Requires-Dist: scikit-learn (>=1.5.2,<2.0.0)
-Requires-Dist: streamlit (>=1.20.0,<2.0.0)
+Requires-Dist: scikit-learn (>=1.5.2,<2.0.0) ; extra == "stats" or extra == "all"
+Requires-Dist: scipy (>=1.10.0,<2.0.0) ; extra == "front-end" or extra == "stats" or extra == "all"
+Requires-Dist: streamlit (>=1.20.0,<2.0.0) ; extra == "front-end" or extra == "all"
 Requires-Dist: tenacity (>=8.0.0,<10.0.0)
 Requires-Dist: tiktoken (>=0.8.0,<0.20.0)
+Requires-Dist: trafilatura (>=1.9,<3.0.0) ; extra == "source-archive" or extra == "all"
 Requires-Dist: typeguard (>=4.3.0,<5.0.0)
 Requires-Dist: unidecode (>=1.4.0,<2.0.0)
 Project-URL: Repository, https://github.com/Metaculus/forecasting-tools
@@ -209,7 +220,6 @@ from forecasting_tools import (
     ReasonedPrediction,
     PredictedOptionList,
     NumericDistribution,
-    SmartSearcher,
     MetaculusClient,
     GeneralLlm,
     PredictionExtractor,
@@ -219,18 +229,13 @@ from forecasting_tools.util.misc import clean_indents
 class MyCustomBot(TemplateBot):
 
     async def run_research(self, question: MetaculusQuestion) -> str:
-        searcher = SmartSearcher(
-            num_searches_to_run=2,
-            num_sites_per_search=10
-        )
+        searcher = GeneralLlm(model="perplexity/sonar-pro", temperature=0)
 
         prompt = clean_indents(
             f"""
             Analyze this forecasting question:
-            1. Filter for recent events in the past 6 months
-            2. Don't include domains from youtube.com
-            3. Look for current trends and data
-            4. Find historical analogies and base rates
+            1. Look for current trends and data
+            2. Find historical analogies and base rates
 
             Question: {question.question_text}
 
@@ -562,6 +567,25 @@ with MonetaryCostManager(max_cost) as cost_manager:
     print(f"Current cost: ${current_cost:.2f}")
 ```
 
+# Optional extras
+Some features need heavier dependencies that a bot does not, so they are opt-in. The base install stays small, and nothing in the template bot or the bot running infrastructure depends on them.
+
+| Extra | You need it for |
+| --- | --- |
+| `agents` | Anything built on the agent SDK: `QuestionDecomposer`, `QuestionOperationalizer`, `TopicGenerator`, `DataAnalyzer`, `Benchmarker`, `BenchmarkForBot`, `BotOptimizer`, `CustomizableBot`, `ComputerUse` (browser-driving agent), and the AI Congress tools |
+| `front-end` | The Streamlit app in `forecasting_tools/front_end/` and `run_benchmark_streamlit_page` |
+| `stats` | `forecasting_tools.util.stats` and the calibration adjusters in `forecasting_tools/calibration_adjustment/` |
+| `all` | Everything above |
+
+```bash
+pip install 'forecasting-tools[agents]'
+pip install 'forecasting-tools[agents,front-end]'
+pip install 'forecasting-tools[all]'
+```
+
+If you use one of these features without its extra installed, you get an error telling you exactly which command to run. Importing `forecasting_tools` itself never requires an extra — the affected names are loaded on first access.
+
+
 # Local Development
 
 ## Environment Variables
@@ -599,8 +623,17 @@ There are many ways to manager Docker containers, but generally if you download
 If you choose not to run Docker, you can use poetry to set up a local virtual environment. If you are on Ubuntu, you should be able to just read through and then run `.devcontainer/postinstall.sh`. If you aren't on Ubuntu, check out the links in the postinstall file for where install instructions for dependencies were originally found. You may also want to take a look at VSCode extensions that would be installed (see the list in the `.devcontainer/devcontainer.json` file) so that some VSCode workplace settings work out of the box (e.g. automatic Black Formatting).
 
 
+## Installing dependencies
+Local development uses the optional extras (the tests cover the front end, the agent tools, and benchmarking), so install with:
+
+```bash
+poetry install --all-extras
+```
+
+A plain `poetry install` gives you only the base dependencies. That is what the bot-running GitHub workflows use, which keeps them honest about the template bot not needing the extras — but it is not enough to run the full unit test suite.
+
 ## Running the Front End
-You can run any front end folder in the front_end directory by executing `streamlit run front_end/main.py`. This will start a development server for you that you can run. Streamlit makes it very easy to publish demos.
+You can run any front end folder in the front_end directory by executing `streamlit run front_end/Home.py`. This will start a development server for you that you can run. Streamlit makes it very easy to publish demos. This needs the `front-end` extra (included in `poetry install --all-extras`).
 
 ## Testing
 This repository uses pytest tests are subdivided into folders 'unit_tests', 'integration'. Unit tests should always pass. You can run `pytest code_tests/unit_tests` or just `pytest` to run all of these

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/README.md

@@ -158,7 +158,6 @@ from forecasting_tools import (
     ReasonedPrediction,
     PredictedOptionList,
     NumericDistribution,
-    SmartSearcher,
     MetaculusClient,
     GeneralLlm,
     PredictionExtractor,
@@ -168,18 +167,13 @@ from forecasting_tools.util.misc import clean_indents
 class MyCustomBot(TemplateBot):
 
     async def run_research(self, question: MetaculusQuestion) -> str:
-        searcher = SmartSearcher(
-            num_searches_to_run=2,
-            num_sites_per_search=10
-        )
+        searcher = GeneralLlm(model="perplexity/sonar-pro", temperature=0)
 
         prompt = clean_indents(
             f"""
             Analyze this forecasting question:
-            1. Filter for recent events in the past 6 months
-            2. Don't include domains from youtube.com
-            3. Look for current trends and data
-            4. Find historical analogies and base rates
+            1. Look for current trends and data
+            2. Find historical analogies and base rates
 
             Question: {question.question_text}
 
@@ -511,6 +505,25 @@ with MonetaryCostManager(max_cost) as cost_manager:
     print(f"Current cost: ${current_cost:.2f}")
 ```
 
+# Optional extras
+Some features need heavier dependencies that a bot does not, so they are opt-in. The base install stays small, and nothing in the template bot or the bot running infrastructure depends on them.
+
+| Extra | You need it for |
+| --- | --- |
+| `agents` | Anything built on the agent SDK: `QuestionDecomposer`, `QuestionOperationalizer`, `TopicGenerator`, `DataAnalyzer`, `Benchmarker`, `BenchmarkForBot`, `BotOptimizer`, `CustomizableBot`, `ComputerUse` (browser-driving agent), and the AI Congress tools |
+| `front-end` | The Streamlit app in `forecasting_tools/front_end/` and `run_benchmark_streamlit_page` |
+| `stats` | `forecasting_tools.util.stats` and the calibration adjusters in `forecasting_tools/calibration_adjustment/` |
+| `all` | Everything above |
+
+```bash
+pip install 'forecasting-tools[agents]'
+pip install 'forecasting-tools[agents,front-end]'
+pip install 'forecasting-tools[all]'
+```
+
+If you use one of these features without its extra installed, you get an error telling you exactly which command to run. Importing `forecasting_tools` itself never requires an extra — the affected names are loaded on first access.
+
+
 # Local Development
 
 ## Environment Variables
@@ -548,8 +561,17 @@ There are many ways to manager Docker containers, but generally if you download
 If you choose not to run Docker, you can use poetry to set up a local virtual environment. If you are on Ubuntu, you should be able to just read through and then run `.devcontainer/postinstall.sh`. If you aren't on Ubuntu, check out the links in the postinstall file for where install instructions for dependencies were originally found. You may also want to take a look at VSCode extensions that would be installed (see the list in the `.devcontainer/devcontainer.json` file) so that some VSCode workplace settings work out of the box (e.g. automatic Black Formatting).
 
 
+## Installing dependencies
+Local development uses the optional extras (the tests cover the front end, the agent tools, and benchmarking), so install with:
+
+```bash
+poetry install --all-extras
+```
+
+A plain `poetry install` gives you only the base dependencies. That is what the bot-running GitHub workflows use, which keeps them honest about the template bot not needing the extras — but it is not enough to run the full unit test suite.
+
 ## Running the Front End
-You can run any front end folder in the front_end directory by executing `streamlit run front_end/main.py`. This will start a development server for you that you can run. Streamlit makes it very easy to publish demos.
+You can run any front end folder in the front_end directory by executing `streamlit run front_end/Home.py`. This will start a development server for you that you can run. Streamlit makes it very easy to publish demos. This needs the `front-end` extra (included in `poetry install --all-extras`).
 
 ## Testing
 This repository uses pytest tests are subdivided into folders 'unit_tests', 'integration'. Unit tests should always pass. You can run `pytest code_tests/unit_tests` or just `pytest` to run all of these

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/forecasting_tools/__init__.py

@@ -1,3 +1,7 @@
+import importlib.util
+import types
+from typing import TYPE_CHECKING, Any
+
 import nest_asyncio
 
 from forecasting_tools.agents_and_tools.base_rates.base_rate_researcher import (
@@ -15,21 +19,6 @@ from forecasting_tools.agents_and_tools.base_rates.niche_list_researcher import
 from forecasting_tools.agents_and_tools.deprecated.question_generator import (
     QuestionGenerator as QuestionGenerator,
 )
-from forecasting_tools.agents_and_tools.other.data_analyzer import (
-    DataAnalyzer as DataAnalyzer,
-)
-from forecasting_tools.agents_and_tools.question_generators.question_decomposer import (
-    QuestionDecomposer as QuestionDecomposer,
-)
-from forecasting_tools.agents_and_tools.question_generators.question_operationalizer import (
-    QuestionOperationalizer as QuestionOperationalizer,
-)
-from forecasting_tools.agents_and_tools.question_generators.topic_generator import (
-    TopicGenerator as TopicGenerator,
-)
-from forecasting_tools.agents_and_tools.research.computer_use import (
-    ComputerUse as ComputerUse,
-)
 from forecasting_tools.agents_and_tools.research.key_factors_researcher import (
     KeyFactorsResearcher as KeyFactorsResearcher,
 )
@@ -66,14 +55,6 @@ from forecasting_tools.ai_models.resource_managers.monetary_cost_manager import
 from forecasting_tools.ai_models.resource_managers.refreshing_bucket_rate_limiter import (
     RefreshingBucketRateLimiter as RefreshingBucketRateLimiter,
 )
-from forecasting_tools.auto_optimizers.bot_optimizer import BotOptimizer as BotOptimizer
-from forecasting_tools.cp_benchmarking.benchmark_displayer import (
-    run_benchmark_streamlit_page as run_benchmark_streamlit_page,
-)
-from forecasting_tools.cp_benchmarking.benchmark_for_bot import (
-    BenchmarkForBot as BenchmarkForBot,
-)
-from forecasting_tools.cp_benchmarking.benchmarker import Benchmarker as Benchmarker
 from forecasting_tools.data_models.binary_report import (
     BinaryPrediction as BinaryPrediction,
 )
@@ -196,4 +177,85 @@ from forecasting_tools.helpers.structure_output import (
 )
 from forecasting_tools.util.misc import clean_indents as clean_indents
 
+# Loaded on first access rather than at import time. These names need optional
+# dependencies (see the extras in pyproject.toml), so importing them eagerly
+# would make `import forecasting_tools` fail for anyone who installed only the
+# base package to run a bot.
+_LAZY_EXPORTS: dict[str, str] = {
+    "Benchmarker": "forecasting_tools.cp_benchmarking.benchmarker",
+    "BenchmarkForBot": "forecasting_tools.cp_benchmarking.benchmark_for_bot",
+    "BotOptimizer": "forecasting_tools.auto_optimizers.bot_optimizer",
+    "ComputerUse": "forecasting_tools.agents_and_tools.research.computer_use",
+    "DataAnalyzer": "forecasting_tools.agents_and_tools.other.data_analyzer",
+    "QuestionDecomposer": "forecasting_tools.agents_and_tools.question_generators.question_decomposer",
+    "QuestionOperationalizer": "forecasting_tools.agents_and_tools.question_generators.question_operationalizer",
+    "TopicGenerator": "forecasting_tools.agents_and_tools.question_generators.topic_generator",
+    "run_benchmark_streamlit_page": "forecasting_tools.cp_benchmarking.benchmark_displayer",
+}
+
+if TYPE_CHECKING:
+    from forecasting_tools.agents_and_tools.other.data_analyzer import (
+        DataAnalyzer as DataAnalyzer,
+    )
+    from forecasting_tools.agents_and_tools.question_generators.question_decomposer import (
+        QuestionDecomposer as QuestionDecomposer,
+    )
+    from forecasting_tools.agents_and_tools.question_generators.question_operationalizer import (
+        QuestionOperationalizer as QuestionOperationalizer,
+    )
+    from forecasting_tools.agents_and_tools.question_generators.topic_generator import (
+        TopicGenerator as TopicGenerator,
+    )
+    from forecasting_tools.agents_and_tools.research.computer_use import (
+        ComputerUse as ComputerUse,
+    )
+    from forecasting_tools.auto_optimizers.bot_optimizer import (
+        BotOptimizer as BotOptimizer,
+    )
+    from forecasting_tools.cp_benchmarking.benchmark_displayer import (
+        run_benchmark_streamlit_page as run_benchmark_streamlit_page,
+    )
+    from forecasting_tools.cp_benchmarking.benchmark_for_bot import (
+        BenchmarkForBot as BenchmarkForBot,
+    )
+    from forecasting_tools.cp_benchmarking.benchmarker import Benchmarker as Benchmarker
+
+
+def __getattr__(name: str) -> Any:
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        # Subpackages used to be bound here as a side effect of the eager imports
+        # that lived above, so keep `forecasting_tools.<subpackage>` reachable.
+        module_path = f"{__name__}.{name}"
+        if importlib.util.find_spec(module_path) is None:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        value = importlib.import_module(module_path)
+    else:
+        # A missing extra surfaces as ImportError rather than AttributeError so
+        # that `from forecasting_tools import Benchmarker` still names the extra
+        # to install. Python rewrites an AttributeError raised here into a bare
+        # "cannot import name" message, which loses those instructions.
+        value = getattr(importlib.import_module(module_path), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))
+
+
+# Without this, `from forecasting_tools import *` would silently skip the lazy
+# names, since a star import only copies what is already bound in globals().
+_IMPORT_MACHINERY_NAMES = {"TYPE_CHECKING", "Any"}
+__all__ = sorted(
+    {
+        name
+        for name, value in globals().items()
+        if not name.startswith("_")
+        and name not in _IMPORT_MACHINERY_NAMES
+        and not isinstance(value, types.ModuleType)
+    }
+    | set(_LAZY_EXPORTS)
+)
+
 nest_asyncio.apply()

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/forecasting_tools/agents_and_tools/base_rates/deduplicator.py

@@ -6,7 +6,6 @@ import random
 import numpy as np
 import requests
 from openai import OpenAI
-from sklearn.metrics.pairwise import cosine_similarity
 
 from forecasting_tools.agents_and_tools.deprecated.configured_llms import BasicLlm
 from forecasting_tools.agents_and_tools.research.smart_searcher import SmartSearcher
@@ -223,13 +222,22 @@ class Deduplicator:
         list_embeddings = embeddings[1:]
 
         for list_embedding in list_embeddings:
-            similarity = cosine_similarity(
-                np.array([text_embedding]), np.array([list_embedding])
-            )[0][0]
+            similarity = cls.__cosine_similarity(text_embedding, list_embedding)
             if similarity > semantic_similarity_threshold:
                 return True
         return False
 
+    @staticmethod
+    def __cosine_similarity(
+        first_vector: list[float], second_vector: list[float]
+    ) -> float:
+        first = np.asarray(first_vector, dtype=float)
+        second = np.asarray(second_vector, dtype=float)
+        magnitude = float(np.linalg.norm(first) * np.linalg.norm(second))
+        if magnitude == 0.0:
+            return 0.0
+        return float(np.dot(first, second) / magnitude)
+
     @classmethod
     def __get_embeddings_using_openai(cls, texts: list[str]) -> list[list[float]]:
         # TODO: Track costs from this in llm cost tracker

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/forecasting_tools/agents_and_tools/question_generators/question_decomposer.py

@@ -170,10 +170,10 @@ class QuestionDecomposer:
         related_research: str | None,
         additional_context: str | None,
         number_of_questions: int = 5,
-        model: str | GeneralLlm = GeneralLlm.search_context_model(
-            "openrouter/perplexity/sonar"
-        ),
+        model: str | GeneralLlm | None = None,
     ) -> DecompositionResult:
+        if model is None:
+            model = GeneralLlm.search_context_model("openrouter/perplexity/sonar")
         llm = GeneralLlm.to_llm(model)
 
         prompt = clean_indents(

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/forecasting_tools/agents_and_tools/question_generators/topic_generator.py

@@ -11,6 +11,7 @@ from forecasting_tools.ai_models.general_llm import GeneralLlm
 from forecasting_tools.helpers.asknews_searcher import AskNewsSearcher
 from forecasting_tools.helpers.structure_output import structure_output
 from forecasting_tools.util.misc import clean_indents
+from forecasting_tools.util.optional_imports import require_optional_package
 
 logger = logging.getLogger(__name__)
 
@@ -46,6 +47,7 @@ class TopicGenerator:
         number_of_topics: int = 10,
         additional_instructions: str = "",
     ) -> list[str]:
+        require_optional_package("faker", "faker", "agents")
         from faker import Faker
 
         if isinstance(model, str):
@@ -216,6 +218,7 @@ class TopicGenerator:
         model: GeneralLlm | str = "gpt-4o",
         search_model: GeneralLlm | str = "openrouter/perplexity/sonar-pro",
     ) -> tuple[OrgInfo, list[str]]:
+        require_optional_package("faker", "faker", "agents")
         from faker import Faker
 
         fake = Faker(cls.LANGUAGES)

{forecasting_tools-0.2.92 → forecasting_tools-0.3.0}/forecasting_tools/agents_and_tools/research/computer_use.py

@@ -2,13 +2,25 @@ import asyncio
 import logging
 import os
 
-from hyperbrowser import AsyncHyperbrowser
-from hyperbrowser.models import CreateSessionParams, CuaTaskData, StartCuaTaskParams
 from pydantic import BaseModel
 
-from forecasting_tools.agents_and_tools.other.hosted_file import HostedFile
-from forecasting_tools.ai_models.agent_wrappers import agent_tool
 from forecasting_tools.util.misc import clean_indents
+from forecasting_tools.util.optional_imports import require_optional_package
+
+require_optional_package("hyperbrowser", "hyperbrowser", "agents")
+require_optional_package("agents", "openai-agents", "agents")
+
+from hyperbrowser import AsyncHyperbrowser  # noqa: E402
+from hyperbrowser.models import (  # noqa: E402
+    CreateSessionParams,
+    CuaTaskData,
+    StartCuaTaskParams,
+)
+
+from forecasting_tools.agents_and_tools.other.hosted_file import (  # noqa: E402
+    HostedFile,
+)
+from forecasting_tools.ai_models.agent_wrappers import agent_tool  # noqa: E402
 
 logger = logging.getLogger(__name__)