GRPC API

Use gRPC to connect to a running GoCPG server: read graph statistics, execute SQL queries, find symbols, and update the CPG. GrpcTransport is CodeGraph’s async Python client for these operations. It returns typed Pydantic result models.

This reference is for integration developers. It covers connection settings, a graph statistics example, operation groups, and error handling. Protobuf files define message formats and remote method signatures.

Canonical services

The generated Python stubs are in src/services/gocpg/proto/gocpg/v1/. For the example below, import the ready-to-use GrpcTransport client from src.services.gocpg.

Connection configuration

Pass a settings object to GrpcTransport(config=connection_config). The client reads its grpc_host, grpc_port, grpc_api_key, and grpc_tls_cert attributes; missing attributes use the defaults in the table. For example, SimpleNamespace from Python’s types module can hold these attributes without a separate configuration class. The grpc_tls_cert path points to a root certificate PEM file on the client filesystem. For a local connection with default settings, use GrpcTransport(), as in the example below.

Send and receive messages are capped at 64 MiB. If grpc_tls_cert is absent, the client uses grpc.aio.insecure_channel; this is suitable only inside an already trusted boundary. Supplying a certificate creates a server-authenticated TLS channel. It does not configure client-certificate authentication.

Read graph statistics

Prepare the Python environment using the installation guide. Run the example from the CodeGraph repository root with that environment activated. A GoCPG gRPC server must have access to the selected CPG. The example connects to localhost:50051 by default. For another address, set CODEGRAPH_GRPC_HOST and CODEGRAPH_GRPC_PORT in the terminal. For a secure connection, set CODEGRAPH_GRPC_TLS_CERT to your root CA path and CODEGRAPH_GRPC_API_KEY to the configured API key. The example reads these variables and passes their values to the client; it does not load settings from config.yaml.

Save the following code as grpc_example.py:

import asyncio
import os
from types import SimpleNamespace

from src.services.gocpg import GrpcTransport


async def main():
    connection = SimpleNamespace(
        grpc_host=os.environ.get("CODEGRAPH_GRPC_HOST", "localhost"),
        grpc_port=int(os.environ.get("CODEGRAPH_GRPC_PORT", "50051")),
        grpc_api_key=os.environ.get("CODEGRAPH_GRPC_API_KEY"),
        grpc_tls_cert=os.environ.get("CODEGRAPH_GRPC_TLS_CERT"),
    )
    transport = GrpcTransport(config=connection)
    try:
        result = await transport.stats(os.environ["CODEGRAPH_CPG_PATH"], timeout=30)
        print(result.total_nodes, result.total_edges)
    finally:
        await transport.close()


asyncio.run(main())

Set the absolute path to an existing CPG and run the file in Bash:

export CODEGRAPH_CPG_PATH="<absolute-cpg-path>"
python grpc_example.py

The output contains two integers: the graph’s node count and edge count. They depend on the selected graph. stats returns a GoCPGStatsResult; its methods, calls, files, and tables fields provide more detail. The finally block closes the channel after success or failure.

Operation groups

• parse, update, ci_update, and create_indexes build or update a DuckDB CPG. Parse and update consume server streams and can report progress through the configured callback.
• query, stats, quality_stats, frontend, branch, and submodule methods use QueryService.
• search, scan, and validate_rule use PatternService; scan is streaming.
• nav_symbols, nav_callers, nav_callees, nav_hierarchy, nav_outline, nav_usages, nav_deps, and nav_resolve use NavigationService.
• lifecycle_status calls GetDatabaseStatus; watch_database_status calls WatchDatabaseStatus; freshness, maintenance, and plan_refresh use the corresponding lifecycle RPCs, including PlanRefresh.

Use the Python method signatures for typed client input and the protobuf files for request fields and the wire contract.

Paths and deadlines

Database-scoped operations require an explicit db_path or typed request field that resolves to one. Source, repository, output, and database paths are normalized to absolute paths before the RPC is sent. The GoCPG server must be able to interpret those paths in its own runtime context; a client-local path is not automatically mounted into a remote server.

The transport applies these default deadlines, in seconds:

• parse: 3600.
• update and ci_update: 600.
• create_indexes, scan, and run_maintenance: 300.
• query, stats, quality_stats, and search: 60.
• validate_rule, navigation methods, unary lifecycle calls, and plan_refresh: 30.
• watch_database_status: 60.

Set the method’s timeout, or the typed request’s timeout field, to change its deadline.

Failure handling

DEADLINE_EXCEEDED is mapped to GoCPGTimeoutError. For parse, FAILED_PRECONDITION with empty_scope details is mapped to EmptyAuditScopeError: the selected scope contains no source files to parse. Other gRPC statuses are mapped to GoCPGProcessError with the status name and server details. A parse or update stream that ends without a final result can return a result model assembled from the requested output path. In parse operations with an explicit audit-scope policy, a missing terminal result instead raises ValueError: audit_scope_invalid_provenance: terminal parse result missing. Verify the expected graph content and provenance separately. A status request shows server availability; the graph content and provenance show which data is available for analysis.

For an unavailable server, first verify host, port, trust chain, and bearer metadata. Then run a lightweight health or metadata call before retrying a long parse. Do not disable TLS or remove the API key merely to turn an authorization or certificate failure into a connection.

Security boundary

The transport sends the configured API key as bearer metadata and validates the server certificate using the configured root CA. Keep credentials in a trusted secret provider and limit the server’s filesystem access to the required paths. Use plaintext insecure_channel inside a protected local network boundary.

Raw db_path belongs to the Python gRPC client. Agent-facing MCP calls resolve storage through project/runtime context.

Help and troubleshooting

See the installation guide to prepare the CodeGraph and GoCPG environment, and the troubleshooting guide for configuration and connection checks. The service table above identifies the message and RPC contracts.