API complexity levels

While designing the components of the problib, I’ve found it difficult to distinguish between the “level” of API for different audiences. What should the API look like for clients that just want to do the barebones and use those pieces that come as a part of the library? How does this differ from those that actually need to extend the base components in some way? Is this flexibility built-in, and how does it complicate things?

For example, while designing the simulation component, I’ve bounced back on forth on how to allow users to specify their own entities inside of the environments. The functionality of these entities can be quite dependent on the use case, and there is no way I could anticipate the ways a user might need to extend the basic entities available. So do I allow basic new entity registration at the basic API level, like env = env.Env(**params) gym = gym.Gym(env) gym.register('new_entity', NewEntity) This is not exactly a real working example, but it demonstrates how I could very easily allow a client to define a new entity NewEntity, and set it up to be registered later on and used within the simulation

This whole discussion also plays into the general issues of not being to decide on generality. How general to a make a class, or function? Should I spent the time and think about, or just implement it and move on? I find it hard to determine the scope, especially when you’re unsure of the components that will depend on it.