feat: user cost

[wjiayis]

#58

Frontend

Database

docker exec mongodb mongosh --quiet paperdebugger --eval "db.llm_sessions.find().forEach(d => printjson(d))"

{
  _id: ObjectId('699950cddf3315112ae7e9bb'),
  user_id: ObjectId('6975da46d6096ac1b07342c2'),
  session_start: ISODate('2026-02-21T06:29:33.980Z'),
  session_expiry: ISODate('2026-02-21T11:29:33.980Z'),
  prompt_tokens: Long('27834'),
  completion_tokens: Long('917'),
  total_tokens: Long('28751'),
  request_count: Long('6')
}

Questions

Are we going to implement a per-user usage cap?

[Junyi-99]

Hi @wjiayis , thanks for another great contribution!

regarding your question: yes, we do need a per-user usage cap.

thanks again!

[wjiayis]

@Junyi-99 No problem! Yea cool, feel free let me know the token limit you decide to have! I feel that having some sort of progress bar would make more sense than the absolute token number.

[Junyi-99]

@wjiayis yeah, a progress bar is much more intuitive than raw numbers.

Since models vary in pricing, let's implement a USD-based cap: Per session: $1, Per week: $2, Per month: $3

Since reasoning models make it hard to calculate exact overhead, let’s also add a small disclaimer in the UI mentioning that the usage is an estimate. We'll run this for a bit and adjust based on the results.

Also, we should support different limits for different users (e.g., tiered usage caps).

What are your thoughts on this tiered pricing approach? Any other suggestions for the plan?

Thanks!

[Copilot]

Pull request overview

This pull request implements user-level token usage tracking to address Issue #58, enabling the system to distinguish between heavy and light users and track LLM token consumption per user. The implementation adds session-based tracking (5-hour windows) and weekly aggregation, with both backend services and a frontend UI to display usage statistics.

Changes:

• Added usage tracking service that records token consumption from OpenAI API responses and stores them in MongoDB with session-based aggregation
• Created new gRPC/REST API endpoints to retrieve current session and weekly usage statistics
• Implemented frontend Usage tab to display token consumption metrics with auto-refresh capability

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
proto/usage/v1/usage.proto	Defines protobuf messages and service for usage tracking API
pkg/gen/api/usage/v1/*.go	Generated Go code for usage service (gRPC server, gateway, protobuf messages)
webapp/_webapp/src/pkg/gen/apiclient/usage/v1/usage_pb.ts	Generated TypeScript protobuf types for frontend
internal/models/usage.go	MongoDB model for LLM session tracking
internal/services/usage.go	Core usage tracking service with session management and weekly aggregation
internal/api/usage/*.go	API handlers for session and weekly usage endpoints
internal/libs/db/db.go	Database index creation for TTL and efficient session lookups
internal/services/toolkit/client/completion_v2.go	Integration to capture usage data from OpenAI streaming responses
internal/services/toolkit/client/utils_v2.go	Enables usage reporting in stream options
internal/services/toolkit/client/client_v2.go	Dependency injection for usage service
internal/services/toolkit/client/get_conversation_title_v2.go	Updated to pass userID for usage tracking
internal/services/toolkit/client/get_citation_keys.go	Updated to pass userID for usage tracking
internal/wire.go, internal/wire_gen.go	Dependency injection wiring for usage service
internal/api/server.go, internal/api/grpc.go	Registration of usage service endpoints
webapp/_webapp/src/views/usage/index.tsx	Frontend UI component displaying usage statistics
webapp/_webapp/src/query/*.ts	React Query hooks and API client functions for usage endpoints
webapp/_webapp/src/paperdebugger.tsx	Added Usage tab to main navigation
pkg/gen/api/chat/v2/chat.pb.go	Generated code formatting change (import order)
internal/api/chat/create_conversation_message_stream_v2.go	Updated to pass userID for usage tracking
internal/services/toolkit/client/get_citation_keys_test.go	Test setup updated with usage service dependency
go.sum	Updated Go module dependencies

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wjiayis]

@Junyi-99 Sure, a USD-based cap makes a lot of sense!

Also, we should support different limits for different users (e.g., tiered usage caps).

Are employing a freemium model and charge heavy-usage users? I think it's a great way to monetize PaperDebugger, balancing ease of onboarding for new users, API costs, and returns for sustained development/maintenance.

Just off the top of my head, I suggest we could roll this out in 2 phases

1. We deploy the token counter on the backend but not display it on the frontend, to observe usage distribution
2. Based on the usage distribution, we launch 3 tiers of usage: Free, Lite and Pro.
   a. Free tier could have the limits of Per session: $1, Per week: $2, Per month: $3
   b. Lite tier could be a reasonable limit that encompass almost all users
   c. Pro tier could be a really high limit for a few users
3. We could also make XtraMCP available exclusively to paid users to increase incentives for subscribing

Alternatively if we decide not to monetize PaperDebugger, I could block all requests past the free tier usage.

[4ndrelim]

Thanks for the good work Jia yi! I haven't yet finished looking through the files, and some parts im not too sure yet, but I will approve first for integration testing on staging and do a deeper review in the meantime before the final PR to main.

[4ndrelim]

Just a quick check, you are using the UserID generated by PD backend right?

I noticed there might be an interesting edge case. UserID i believe is generated by user email address on overleaf. Now, if the user logs in via Overleaf, a UserID is generated. If the same user logs in via google account, I think a different UserID for the same user might be generated too (it'll be the same if the same gmail is registered on Overleaf).

Ideally we should recognise and combine / avoid re-generating UserID. But this is a separate problem and requires a fix (if indeed the case) that should not be overloaded on this PR.

If its convenient, could you also test and verify during integration testing? Can try two different login methods on the same Overleaf project and we should expect two tokens usage tracking.

[wjiayis]

Yup, it's the UserID generated by PD backend. Sure, will take note when testing. I also wonder if a user could just keep switching emails for the same Overleaf project. Shall we have a per-user limit and a per-project limit?

cc: @Junyi-99

[4ndrelim]

yeah switching out emails will generate a different UserID i believe. Not sure if having a limit on ProjectID is wise because we can have diff collaborators working on the same project.

Edit: Not sure if Overleaf has any safeguards / cooldowns on switching out emails too frequently. But yeah, we can keep this in mind since its a separate problem. Ideally UserID is generated in a way that it is unique and accurately tied to account.