forze

Uses Forze queue, pub/sub, and stream contracts with QueueSpec, PubSubSpec, StreamSpec, SQSDepsModule, RabbitMQDepsModule, Redis adapters, and Mock adapters. Use when producing, consuming, or testing async messages/events.

Implements Forze document and search access the kit-first way: DocumentFacade and SearchFacade over build_document_registry / build_search_registry, kit DTOs (DocumentIdDTO, ListRequestDTO, DocumentUpdateDTO), the query DSL, pagination, cache-aware DocumentSpec / SearchSpec, and the Postgres / Mongo / Firestore / Meilisearch backends behind them. Use when building data access features.

Optimize code only after a real, measured performance problem - distinguish macro (design-level) from micro (fine-tuned) performance, reach for data-structure and algorithm wins before micro-tweaks, profile to find real hotspots, and don't trade readability or adaptability for unmeasured speed. Use when optimizing code, reviewing performance suggestions, choosing "faster" constructs, or when the user mentions performance, optimization, speed, or efficiency.

Name variables, functions, classes, and modules well by avoiding known anti-patterns - single letters, abbreviations, types baked into names, missing units, "Base"/"Abstract" class names, and "Utils"/"Helper" grab-bags. Use when naming or renaming code, reviewing names in a diff, or when the user mentions naming, identifiers, variable names, readability, or that a name feels off.

Keep code flat and readable by limiting indentation depth, using guard clauses with early returns, and extracting nested blocks into well-named functions. Use when writing or refactoring code with deep nesting, pyramid-shaped if/else, arrow code, or when the user mentions nesting, indentation, guard clauses, early returns, extracting functions, cyclomatic complexity, or making code more readable.

Make code explain itself instead of relying on comments - name sub-expressions, extract complex conditions into well-named functions, lean on the type system, and reserve comments for the "why" the code cannot express. Use when writing or reviewing comments, refactoring hard-to-read logic, deciding whether a comment is needed, or when the user mentions comments, self-documenting code, or code readability.

Write consistent Python docstrings in Google style with typed sections. Use when writing or updating docstrings, documenting Python code, or when the user mentions docstrings, Google style, Napoleon, or API documentation.

Wires and consumes Forze analytics with AnalyticsSpec, AnalyticsQueryPort (run / run_page / run_cursor) and AnalyticsIngestPort (append), named parameterized SQL templates, and the BigQuery (BigQueryDepsModule, @param SQL) and ClickHouse (ClickHouseDepsModule, {name:Type} SQL) backends, plus MockAnalyticsAdapter tests. Use when adding warehouse queries or streaming append.

Uses Forze authn/authz, tenancy, call context, secrets, routed clients, and FastAPI/worker identity binding. Use when adding authentication, authorization, tenant-aware infrastructure, secret-backed configuration, or external IdP integrations such as OIDC, Casdoor, or Firebase Auth.

Authors custom DepKey and DepsModule implementations in an application when a private integration is not covered by shipped forze_* packages. Use for Neo4j graph adapters, Redis pub/sub maps, or other app-specific backends.

Explains how Forze resolves dependencies in applications: plain vs routed Deps, route=spec.name, built-in DepsModule composition, and merge conflicts. Use when debugging handler resolution or wiring Postgres, Redis, S3, and other shipped integration modules.

Defines Forze document aggregates (Document, commands, ReadDocument), mixins, validators, logical DocumentSpec and SearchSpec. Use when modeling entities, DTOs, StrEnum-backed DocumentSpec, SearchSpec, CacheSpec, or aligning schemas with Forze domain and application contracts.

Connects Forze handlers to FastAPI: runtime context dependency and lifespan, generated routes from an operation registry (attach_document_routes / attach_search_routes / attach_storage_routes), SecurityContextMiddleware identity binding, custom headers/logging middleware, Scalar docs, and CoreException error handling. Use when exposing handlers over HTTP.

Guides correct use of Forze ExecutionContext, document/query/command ports, search, cache, counters, storage, messaging, workflows, identity, and transactions in handlers. Use when implementing features or handlers with Forze specs, hexagonal ports, or runtime context.

Models Forze graph contracts with GraphModuleSpec, GraphNodeSpec, GraphEdgeSpec, graph refs, query/command ports, and dependency keys. Use when adding graph-shaped features and wiring a Neo4j or Arango-style adapter in your application.

Calls external HTTP APIs from Forze handlers with declarative BaseHttpIntegration / async_http_op operations, HttpServiceSpec, HttpDepsModule, static and tenant-routed clients, auth, and mock tests. Use when a handler needs to call a remote service over HTTP.

Wires Forze durable function contracts with DurableFunctionEventSpec, DurableFunctionSpec, InngestDepsModule, event emit, function registration, DurableFunctionStepDepKey, and FastAPI serve. Use for event-driven durable handlers with Inngest in applications using forze[inngest].

Wires and consumes Forze object storage with StorageSpec, the StorageFacade / build_storage_registry kit, StorageQueryPort / StorageCommandPort, the S3 (S3DepsModule) and GCS (GCSDepsModule) backends, tenant-aware buckets, lifecycle, upload/download/list/delete and presigned/multipart uploads, and MockStorageAdapter tests. Use when adding blob/file storage on S3-compatible or Google Cloud Storage backends.

Applies Forze structured errors (CoreException / exc factories), logging configuration, call-context binding, OpenTelemetry context injection, and FastAPI error mapping. Use when adding error handling, diagnostics, or logging.

Adds fault tolerance and production hardening to a Forze app: resilience policies (retries, rate limits, circuit breakers, bulkheads), invocation deadlines and time budgets, graceful shutdown/drain, readiness probes, and fleet (multi-replica) deployment posture. Use when configuring timeouts, retries, throttling, adaptive concurrency, or deploying replicas behind a load balancer.

Maps logical specs (DocumentSpec, SearchSpec, CacheSpec, CounterSpec) to integration configs on PostgresDepsModule, MongoDepsModule, RedisDepsModule, S3DepsModule, queue/workflow modules, and transaction routes. Use when wiring logical StrEnum spec names to tables, collections, namespaces, buckets, queues, or deps-module routes.

Wires and uses Forze durable workflow contracts with DurableWorkflowSpec, DurableWorkflowCommandDepKey, DurableWorkflowQueryDepKey, TemporalDepsModule, lifecycle, context propagation, tenant-aware workflow IDs, and Temporal tests. Use when orchestrating long-running workflows.

Wires Forze ExecutionRuntime, DepsRegistry, lifecycle, built-in deps modules, document/search composition, operation pipeline stages, and interface entry points. Use when bootstrapping an app or composing runtime, lifecycle, and operation registries.

Write, polish, review, or align documentation pages to a consistent, production-grade standard using the altitude model (a deliberate high-level to low-level descent), Diátaxis-based page contracts, a shared consistency layer, and a ship rubric. Use when creating, revising, reviewing, or aligning documentation pages, or when deciding where new doc content belongs.

Format git commit messages and Pull Request titles using Conventional Commits with a deterministic gitmoji prefix. Use when generating or suggesting commit messages, PR titles, or when the user says "commit this", "create PR", "write a commit", "prepare PR", or similar.

Maintain CHANGELOG.md in Keep a Changelog format by updating Unreleased and version sections with user-relevant changes.

Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments. Triggers Greptile review, fixes all actionable comments, pushes/re-shelves, re-triggers review, and repeats. Use when the user wants to fully optimize a PR/MR/CL against Greptile's code review standards.

Profile and optimize Python code using cProfile, memory profilers, and performance best practices. Use when debugging slow Python code, optimizing bottlenecks, or improving application performance.