Stable user API and ease of use (e.g. incl. within google colab)

[gavento]

Includes some stability of the log JSON (for better backwards compatibility vs future UI updates and other tools), and having examples / starting templates for users based on that.

If we run experiments in Google colab, I expect it to have an issue with the UI (as the port opened on the colab server is not accessible). @spirali would this be solved by Jupyter-like lab UI-embed into colab? Or is there some other solution? (Or another notebook hosting? ;-)

[gavento]

Mostly achieved after #7 but with some outstanding bikeshedding:

• llm module is not just about llms, but more about engines (some of them LLMs), parsing (from LLMs), ...
• singular or plural for modules?
• etc ... but can also likely just stay as-is

[gavento]

More refactoring, naming and bikeshedding!

Mixture of high-level with some low-level naming bits. Incomplete but good to be criticized!

• contex - Context, logging, context loading/filtering, special context types

  • have a store module? (to have more than JSON in time)
  • Move cotext-logging related classes fron util/ to context (Blob, Html, ...)
  • Rename __log__ to less generic (to make it future-proof), e.g. _log_to_context

• ui - servers for browser, console, ...

  • ... to have (semantic) separation between our concrete UI impls and general store/context?

• actors

  • memory as submodule, moving format under memory
  • experimental - experimental memory impls
  • experimental - experimental actor impls
  • TODO: how to name/distinguish general (but with concrete wording) actor implementations from general framework? contrib? (eh) keep them in experimental forever? (nah) some other module naming scheme here? (maybe) or separate into other dirs? (e.g. move one-shot agent into models? nah) (or have top-level contrib-like dir? seems like cop-out, ...)

• text - text utils: json_parsing, fmtstring, parse_tag

  • consistent naming parsing to parse_json, parse_tag, ...
  • move other text utils we have

• models (or llm, text_models?) - engine wrapping (as integration of other engines still with logging and common interface), our engines (maybe remove in favor of langchain only), query_for_json and friends (query for example of a JSON, cache of examples)

  • experimental - experimental engines and functionality (future: query LLM with activation vectors)

• utils - minimalistic

  • colors - add simple color manipulation (for context styling), have pseudo_random_color here

• ext - as is now, general integrations with other services/libraries/...

Some future bits that will need placing

• Activation vectors: Engines that accept or return activation vectors, some basic manipulation of those (though mostly numpy), logging of those vectors, maybe some vis (?)
• Stateful games API (both for LLM agents and game theory, preferably picklable)
• Remote actor protocol (both for human players)
• Game theory algorithms (RL, maybe CFR; maybe as a separate lib)
  • Also interoperability with Gymnasium (OpenAI gym), some text adventures, etc.
  • A few concrete environments/games (for now built-in, later maybe as a separate lib)
  • Maybe a small lib of game/environment components (discussion channel, man-in-the-middle, ... but also maybe cards+hand, ...)
• New visualization bits for various components and utilities
• Active inference algorithms (lot of uncertainty here, likely at least discrete state, and DL-based; maybe as a separate lib)
• More visualization integration (more than matplotlib, e.g. interactive via plotly etc.)
• Maybe/future: Lobby (?) for AIs and humans (again, likely a separate lib?)

Generators

I want users and prospective developers to have a mental model of this being both:

1. Approachable and batteries-included with good discoverability (we are mostly good on that)
2. Well-structured to serve as basis for future development and other libs (to attract cooperation rather than people making their own libs just because they don't like our one-shot-actor, UI server, JSON querying helpers, some detail about engine backend, ...
   • While my taste is somewhat against prematurely-branching source code trees with mostly empty directories and a lot of separation, I would lean more in that direction to encourage more development - in a sense to create space for it.
   • Same goes for having experimental and contrib modules - to invite people to just write their concrete (and unpolished) semi-general LLM agents and their modules

@spirali @klao please add more:

• small renames and minor refactors (look at the code and say what seems pit of place or not intuitive - we can now rename anything)
• critique or improve the module structure above (or make a new one etc)
• brainstorm possible extensions (just to get the module structure right)

[spirali]

Structure

I agree with new code structure (especially to move server stuff outside of context module)

I would make "actors" only for generic abstract API. And then have different module for all actor implementations with some substrucutre (I do not have right name for the module now).

Activations

Activation vectors will probably needs one extra feature: storing binary data next to context jsons and have a link to these files in contexts. We cannot probably store it directly into context json because of size.

Renaming

The only thing that is in my mind is "add_event" for instant context, that now have clash with "Events" in memory subsystem.

[gavento]

Closed by #29