Skip to content

Update namespaces in architecture to domain-based #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 17, 2025

Conversation

borkweb
Copy link
Contributor

@borkweb borkweb commented Jul 15, 2025

This PR is in draft mode while we contemplate #21.

Reorganized classes into more specific namespaces to match #21. Moved message-related classes, file types, models, and enums into their appropriate sub-namespaces to improve code organization and follow single responsibility principle.

You can see the ARCHITECTURE.md here.

Reorganized classes into more specific namespaces to match #21. Moved message-related classes, file types, models, and enums into their appropriate sub-namespaces to improve code organization and follow single responsibility principle.
@JasonTheAdams
Copy link
Member

@borkweb Regarding #21, are we just waiting for @felixarntz's response to #21 (comment)?

@borkweb
Copy link
Contributor Author

borkweb commented Jul 15, 2025

I was going to wait for the 👍 from both of you. There's also the question at the bottom of that regarding prefixes and suffixes that are a bit redundant. I'm not sure how y'all feel about that piece.

@felixarntz
Copy link
Member

I left some feedback in #21, let's iron that out first. Then we can update this PR as needed and review the details.

@felixarntz felixarntz mentioned this pull request Jul 15, 2025
16 tasks
@borkweb borkweb marked this pull request as ready for review July 15, 2025 20:34
Copy link
Member

@JasonTheAdams JasonTheAdams left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good!

Copy link
Member

@felixarntz felixarntz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@borkweb Thank you for all the updates in accordance with #21!

Almost LGTM, just a few small notes.

Comment on lines 622 to 644
namespace AiClient.Providers.Models.Enums {
class ModalityEnum {
TEXT
DOCUMENT
IMAGE
AUDIO
VIDEO
}
class FinishReasonEnum {
STOP
LENGTH
CONTENT_FILTER
TOOL_CALLS
ERROR
}
class OperationStateEnum {
STARTING
PROCESSING
SUCCEEDED
FAILED
CANCELED
}
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a good mental cross-check to see that this namespace currently remains relevant for the Implementer API (as this class diagram is only that part).

If we are going to be strict about it, we should probably move this to another namespace outside of AiClient.Providers. Since modalities are definitely relevant for implementers (as they can directly reference it when creating a prompt), and FinishReason belongs to Result, and OperationStateEnum belongs to Operation, I'd say it makes sense to move this to other Enums namespaces outside of AiClient.Providers.

Copy link
Contributor Author

@borkweb borkweb Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finding a home for ModalityEnum is a little challenging. It feels like Models/Enums is the right home, but we don't/won't have a top level Models/ directory. So...I plopped it in a top level Enums/ directory.

Since this is the last holdout of this body of work, if you have an idea that makes sense - definitely push a commit to this PR or merge if we're good here 🕺

Copy link
Member

@JasonTheAdams JasonTheAdams Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a thought this morning! What if we did this:

  1. Make a Prompts namespace
  2. Move the PromptBuilder to Prompts
  3. Move the MessagesBuilders to Messages`
  4. Put the common enums we want folks to be thinking of for prompts into the Prompts domain

That, or we move Enums to Builders.Enums. In any case, in keeping with the implementors thinking, we move the prompt builder and its commonly related parts close together.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like bullets 1-4 as an approach. I think it - at the very least - makes PromptBuilder more findable as Builders isn't as intuitive of a directory name. It also makes sense that the MessageBuilder would exist in Messages.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I see how finding a home for ModalityEnum isn't as straightforward as the other two (which I see you already migrated, and LGTM 👍 ).

But I don't think we should add a Prompts namespace, primarily because a "prompt" is not an actual thing in this SDK. There's no Prompt class for example, and the only thing that uses the term is PromptBuilder. To me, "prompt" is the higher-level term for whatever is sent to the model altogether - but if we made that a namespace, it would mean almost every other root level namespace could fall under it, which I find confusing.

IMO, ModalityEnum fits best under AiClientNamespace.Messages.Enums. Every Message consists of parts of different modalities, and that applies to both prompts as well as responses/results (for both of which Message is used).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a case can be made in either direction, tbh. But ultimately, I'm not too picky and can get behind either option, so let's go with @felixarntz 🎈

borkweb added 2 commits July 17, 2025 08:59
…plementer API area. Resolve alphabetization issues. Replicate Tools in both Implementer and Extender areas
Copy link
Member

@felixarntz felixarntz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Except for the point on ModalityEnum, this LGTM.

I left some feedback on that comment thread. The more I think about it, the more intuitive I find for this to be under the Messages namespace.

@felixarntz felixarntz added the [Type] Developer Documentation Documentation for developers label Jul 17, 2025
Copy link
Member

@felixarntz felixarntz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @borkweb!

LGTM, this looks a lot cleaner for the structure than before. If additional ideas come up, we can further discuss or iterate in subsequent issues/PRs.

I'm going to update #20 accordingly based on this.

@felixarntz felixarntz merged commit 3b2daf3 into trunk Jul 17, 2025
@borkweb borkweb deleted the fix/namespace-references-in-architecture branch July 17, 2025 20:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants