smartgrpc Agent Guide

Project Goal

smartgrpc is a small Python framework that lets developers declare gRPC APIs with:

• pydantic.BaseModel for messages
• enum.IntEnum for enums
• Python classes and methods for services

The framework then:

1. registers decorated elements in SmartGrpcApplication
2. renders .proto files from Python declarations
3. compiles protobuf stubs with grpcio-tools
4. adapts protobuf requests/responses to Pydantic models on server and client sides

The current repo now has a productionized synchronous v1 core: schema generation, runtime adapters, compatibility checks, and regression tests are in place. Remaining gaps are mainly async/platform concerns and deeper socket-level integration coverage.

Repository Layout

• src/smartgrpc/application.py Main entry point. Holds the registry, decorator helpers, proto generation, compilation, and server startup.
• src/smartgrpc/decorators.py Decorators for @message, @enum, @service, and @interface.
• src/smartgrpc/registry.py Collects declared elements and groups them by source file for rendering.
• src/smartgrpc/render.py Turns registered Python types into proto snippets.
• src/smartgrpc/templates.py Jinja2 templates used by the renderer.
• src/smartgrpc/protos.py Writes .proto files and invokes protobuf compilation.
• src/smartgrpc/server.py Builds runtime gRPC servicer adapters around user-defined service classes.
• src/smartgrpc/client.py Builds runtime client wrappers around generated gRPC stubs.
• src/smartgrpc/convert.py Converts between protobuf messages and Pydantic models, including oneof and well-known types.
• src/smartgrpc/types.py Scalar type aliases and runtime type tagging helpers.
• examples/bookstore Official example covering include(), cross-file references, and all 4 synchronous RPC shapes.
• tests Regression suite covering render, convert, runtime adapters, schema generation, compatibility, streaming, and well-known types.

Intended Usage Flow

Typical usage in this repo is:

1. create sg = SmartGrpcApplication()
2. decorate models with @sg.message
3. decorate enums with @sg.enum
4. decorate service classes with @sg.service
5. decorate RPC methods with @sg.interface
6. call sg.generate()
7. call sg.compile()
8. run sg.run()
9. create a client with create_client(service_class=..., app=sg, target=...)

Current Gaps And Risks

• async APIs, interceptors, TLS/auth helpers, and DI are not implemented.
• Arbitrary Union[T1, T2, ...] mapping is still intentionally unsupported beyond explicit oneof_field(...).
• Socket-level real-network integration coverage is still thinner than adapter-level coverage.
• Example runs generate protobuf artifacts in-place; regenerate them from source rather than editing generated files manually.

Working Rules For Future Changes

• Prefer changing library code under src/smartgrpc before editing generated _pb2.py files.
• If protobuf outputs need to change, regenerate them from source declarations rather than patching generated files manually.
• When changing message conversion behavior, verify both directions:
  • Pydantic -> protobuf
  • protobuf -> Pydantic
• When changing rendering behavior, validate with at least one example app and inspect the generated .proto.
• Preserve Python 3.12 syntax already used by the project.
• Prefer rg for code search.

Local Dev Commands

• Install deps: uv sync
• Lint/format/type-check: make format
• Run example server: uv run python examples/bookstore/server.py
• Run example client: uv run python examples/bookstore/client.py

Recommended Near-Term Milestones

1. Add socket-level integration tests around the bookstore example.
2. Design router-style composition on top of include().
3. Add async/interceptor support.
4. Add service factory / DI support.
5. Expand production docs around deployment and compatibility workflows.