package names

[tischi]

@kevinyamauchi @haesleinhuepf

Do we really needs the underscores in _machinery and _utilities?

chatGPT4.0 thinks:

---

In Python, underscores in package and module names are not particularly common, but they can be used. There are a few scenarios or reasons why underscores might appear:

1. To Avoid Naming Collisions: If a package or module name would conflict with a built-in Python module or a standard library module, an underscore can be added as a prefix to avoid the collision. For example, if you want to create a module named string, you might name it _string to avoid confusion with the built-in string module.

2. For "Private" or Internal Packages/Modules: Sometimes, an underscore is used as a prefix to indicate that a package or module is meant for internal use and not part of the public API. This follows the convention that names starting with an underscore are considered "protected" or "private" in Python. However, note that this doesn't enforce any actual privacy; it's just a convention.

3. If the Name is a Reserved Keyword: Python keywords cannot be used as module names. If you absolutely want a module name that matches a Python keyword (though it's generally not recommended), you might use an underscore to avoid the conflict. For instance, import is a keyword, so if you had a reason to name a module that, you might use _import.

4. To Make the Name More Readable: In some cases, underscores are added to make the name more readable, especially if the name consists of multiple words. However, this is more common for function and variable names than for module or package names. For modules and packages, hyphenated names are often converted to underscores when the package is imported. For example, the package date-util might be imported as date_util in Python.

5. Legacy or Historical Reasons: Sometimes, the name might have an underscore because of historical reasons, even if none of the above reasons apply.

In general, if you're creating a new package or module, you should avoid using an underscore unless one of the above reasons applies. Choose a name that's descriptive and doesn't conflict with existing modules, and follow the prevailing conventions of the Python community.

---

I don't think we match any of those use-cases, do we?

[haesleinhuepf]

We match case 2. I tend to make everything private per default and later potentially open the API if necessary. Otherwise, if the entire API would be public, we would have breaking backwards-compatibility all the time.

[tischi]

Currently one needs to write code like this:

from bia_bob._machinery import Context, init_assistant
Context.verbose = False
init_assistant("gpt-4") 

From my POV the Context and init_assistant methods are public, but maybe I am seeing this through wrong Java glasses? :-)

[haesleinhuepf]

You can also write bob.initialize("gpt-4") as demonstrated here: https://github.com/haesleinhuepf/bia-bob/blob/main/demo/choose_model.ipynb

The verbose thingy was indeed hidden in private API becaue I wasn't sure if this survives mid-/long-term.

[tischi]

This is the public entry point: from bia_bob import bob