add mostly claude-gen usage example package

[swelborn]

---

This is part 14 of 23 in a stack made with GitButler:

•  23  use historical=True as a fallback if job not found #52
•  22  test coverage for credential boundary #51
•  21  remove "force" option for cache shutdown #50
•  20  client/service/workflow changes for IRI token delegation changes #49
•  19  add cache table to track caches #48
•  18  authenticated principal + encrypted delegated-credential capture #47
•  17  OIDC transfer ownership and delegated user credentials #46
•  16  WIP for shared cache shutdown #45
•  15  add jobspec override #44
•  14  add mostly claude-gen usage example package #43 👈
•  13  ability to share a cache amongst different transfers #42
•  12  add precommit hook for checking openapi client drift #40
•  11  pin python version to 3.14 #41
•  10  build frontend image in CI #39
•  9  add frontend #38
•  8  add frontend client (autogenerated) #37
•  7  lazily construct settings #36
•  6  add autogenerated client #35
•  5  add alembic #34
•  4  add ability to get logs from v2 api services thru iri #29
•  3  functional core tests for transfer and producer #30
•  2  api with durable execution and saga #28
•  1  deps for v2 #27

[frobnitzem]

Why is there a client code added to the API? It belongs in a separate client package. Please submit this PR to https://github.com/lcls-users/lclstream.git

[swelborn]

Since there is CI involved, I would rather keep this all in the same repo.

Eventually, I think we should migrate all of the fragmented packages we have in this org into a monorepo, it makes CI/CD much more straightforward, and allows us to suck up context for agents in one place rather than requiring people to manage their own workspace. uv allows us to do this very simply with workspaces.

This is a separate python package with a separate pyproject.toml - you can just refer to it differently in your dependencies ("lclstream-api-client @ git+https://github.com/lclstream/lclstream_api.git@add-client-example#subdirectory=client/").

[frobnitzem]

If you want a super-repo, why not create a new one for that purpose and put all 4: lclstream_api, lclstream, lclstreamer, and fastcache into it as git submodules?

[swelborn]

submodules is a strategy for this, but i would argue not the best. it does not cover CI very well, and for each commit in a submodule, you have to make another commit to the submodule repo for every merge done in one of the submodules, another maintenance burden. it can also be quite confusing to work with

i laid some of my arguments out for this in slack:

the main issue I take with a polyrepo setup on a small team is that people start to lose track of what other people are doing, and get siloed into their own repo rather than doing code review. Google uses a monorepo for most of its software, for example, and they are an enormous organization with hundreds of applications/teams.

As long as we all take the time to review each others code, I think that the separation is fine. However we end up losing the ability to share CI/CD, connect data models and libraries together easily, etc. If we add a frontend app or react library in the future, for example, do we put that in another repo? How do we coordinate releases between lclstream_api, lclstreamer, fastcache, fastcache_api, and frontend? At the end of the day this is a single product we are shipping.

This is a pattern I see all over the place at slac, the code sprawl is significant. One reason appears to be that people have been burned by monorepos in the past...