[API design] Remove "AI" prefix everywhere

[aozherelyeva]

See #215

[aozherelyeva]

@devcrocod @EugeneTheDev could you please take a look at @ptitjes suggestions and share your thoughts? Thank you!

[EugeneTheDev]

In some of our earlier discussions we touched on this topic, and there was a good point mentioned: Agent is qutie a generic term, and in real-world codebases, there might be other "agents" present. Having AI prefix might prevent name collisions at least to a certain extent. And also if someone not familiar with the framework is reading the code that uses it, they might get confused about what exactly this Agent is and what it does. Having a bit more descriptive name with AI prefix might help here too. So I think we should leave it.

[ptitjes]

Does Koog allow the user to do other kinds of software agents than AI agents? If not, then I still think the prefix is superfluous.

Also, we have import aliases to prevent name collisions.

Finally, if you think that it is absolutely necessary to keep the AI prefix on the AIAgent class for the client's understanding, maybe it can be removed from some other symbols listed in my proposal. Because, the use of the prefix is not consistent at all: some classes/interfaces from the core have it and some don't.

[EugeneTheDev]

Does Koog allow the user to do other kinds of software agents than AI agents?

No, the point was about existing codebases and that these might have other types of "agents", because the term itself is quite geneirc.

Also, we have import aliases to prevent name collisions.

True, but IMHO these are not very convenient and readable when used extensively.

Finally, if you think that it is absolutely necessary to keep the AI prefix on the AIAgent class for the client's understanding, maybe it can be removed from some other symbols listed in my proposal. Because, the use of the prefix is not consistent at all: some classes/interfaces from the core have it and some don't.

Fair point, but this comes down to the current API design, please see my message below

[nathanfallet]

I agree with @EugeneTheDev; Moreover, removing this prefix would be a breaking change and cause a lot of merge conflicts (because there are a lot of concurrent PRs)

[ptitjes]

removing this prefix would be a breaking change and cause a lot of merge conflicts (because there are a lot of concurrent PRs)

I don't think that is a valid argument. Isn't the goal of being in version < 1.0 to cleanup the API? It is customary for libraries in version 0.X.y to introduce breaking changes.

As for the particular proposed change here, it can easily be handled through deprecations.

[ptitjes]

@nathanfallet just to clarify, I didn't say it had to be done now (though in my opinion, the sooner the better). But I believe these kinds of API enhancements must be done before 1.0.

Also we have OpenRewrite to help user migrations.

For instance, Exposed had a lot of breaking changes for its 1.0 version, and I believe it was the right move from JB as it enhanced and cleaned the API. And there are OpenRewrite rules available to mitigate the users' migration, so...

[ptitjes]

I understand @EugeneTheDev 's argument though I only agree with it to a certain extent. Because this leads to extra long interfaces and class names.

This is exacerbated by a lot of the concepts being duplicated, often uselessly, with a class and a Base interface, all of that exposed publicly.

This is similar to for the method names choices. There are so many methods with really close names but one or more different words, all of them defined publicly, also with consistency problems.

Because of that, the API is currently very difficult to discover, understand and use, with too many public APIs. Even these days, a lot of PRs are merged with a bunch of new public symbols, when these mostly should be made internal.

A lot of these problems come from the fact that explicitApi mode is actived in most modules, but the API dumps and checks are not set up.

Finally, I'd like to add that a lot of these design/naming choices go against JetBrains' own guidelines for library authors...

[EugeneTheDev]

@ptitjes I mostly agree with your points here, and I have similar concerns. Unfortunately, given the current (quite rapid) pace of development and the scope we want to cover, it is problematic to address these issues. A lot of new functionality is being added, refactored, or changed, which is to be expected at this stage of framework development. We definitely need to address this before the first stable release though, that's true. But if you have any suggestions on how we can improve the current situation, we would be glad to hear them.

[ptitjes]

So as for some initial actionable items (and quick-wins in my opinion) that touch both this discussion and #373, I propose to:

• make AIAgentTool internal and only keep AIAgent.asTool() public.
• make McpTool internal.

Would you mind that I open tickets for these? (and PRs)