MAINT CONTROVERSIAL: Make env files configurable

[rlundeen2]

This PR updates how initialize_pyrit_async loads environment files, adding support for explicitly specifying .env files while making default loading behavior stricter and more predictable.

Environment Variable Precedence (lowest to highest priority)

1. System environment variables — Always loaded first as the baseline.
2. Default files — If no env_files argument is provided, PyRIT attempts to load ~/.pyrit/.env and ~/.pyrit/.env.local (if they exist). Values in these files override system environment variables.
3. Explicit files — If env_files is passed to initialize_pyrit_async, only those files are loaded (default paths are ignored). Later files in the sequence override earlier ones.

[romanlutz]

So if I provide them with the arg it overrides any auto-detected ones. But what if I provide just .env via arg and .env.local from the directory? There are so many cases 🤷🏻‍♂️ or a completely different one like .env.roman? Hmm maybe being explicit is preferable?

[rlundeen2]

So if I provide them with the arg it overrides any auto-detected ones. But what if I provide just .env via arg and .env.local from the directory? There are so many cases 🤷🏻‍♂️ or a completely different one like .env.roman? Hmm maybe being explicit is preferable?

If you supply any to initialize_pyrit, those are the only .env used. It only looks in the package directory if you don't pass any. Not too unpredictable imo.

So imagine you have to specify or set them yourself; this is close to how we used to do it. In the past people would load their own environment beforehand.

• Jupyter notebooks don't reliably reload an environment. So you have to remember to run a script or load them before every run, especially if they change. If you update, you sometimes had to completely restart jupyter, not just the kernel. It used to be one of the first steps I would do to debug every operator and team member, and it was an issue 70% of the time. Today it is almost a non-issue.
• Even if we add it as an arg to every notebook, users for the CLI/frontend have to load it. So they have to either remember or figure out how to update it. And if we add it to a script (like download secrets), great, but we need to make sure they persist on every OS that uses that.

[romanlutz]

I think we should document the behavior in some way. Perhaps in the .env_example file as well. I'm happy with where you landed in terms of code changes, though! Thanks for hearing me out on the many concerns 😆