Python client for Polaris service discovery, registration, service governance, AI Registry resources, observability, and TLS.
The distribution is polaris-python; import it as polaris.
The categorized documentation index is docs/README.md.
Requires Python 3.12+.
uv sync --group dev --locked
uv run pytest
The project uses a src layout. uv sync installs src/polaris/ in editable mode,
so source changes take effect immediately.
See Version and release for release and development package publishing.
global:
serverConnector:
addresses:
- ${POLARIS_SERVER_ADDRESS:127.0.0.1:8091}
token: ${POLARIS_TOKEN:}
Use Configuration.from_file() for YAML, Configuration.from_env() for environment
variables, or Configuration.from_dict() for code-owned mappings. Python durations
are integer milliseconds; YAML also accepts values such as 500ms, 1s, and 1m30s.
See:
- Configuration parameters
- Minimal YAML example
- Environment variables and precedence
- Minimal file example
Each SDKContext owns its configuration snapshot, client ID, plugins, connections,
caches, tasks, and logs. Reuse one context for APIs that should share that client.
from polaris import Configuration, init_context_by_config
config = Configuration()
config.set_default()
config.get_global().get_server_connector().addresses = ["127.0.0.1:8091"]
context = init_context_by_config(config)
try:
...
finally:
context.destroy()
API calls after destroy() raise SDKError.
ProviderAPI supports synchronous methods and async_ counterparts.
register_instance() enables SDK-managed heartbeats by default.
from polaris.pkg.model.server import InstanceRegisterRequest
response = provider.register_instance(InstanceRegisterRequest(
service="demo",
service_token="service-token",
namespace="default",
host="127.0.0.1",
port=8080,
ttl=5,
))
The service token authorizes register, heartbeat, and deregister. It is different
from POLARIS_TOKEN, which authenticates the SDK connection.
Automatic re-registration runs after two consecutive 400202 responses and
provider.minRegisterInterval.
Deregistration stops heartbeat tasks before the RPC. Context destruction does not
implicitly deregister instances.
Reuse one ConsumerAPI per context. Synchronous calls are get_one_instance(),
get_instances(), get_all_instances(), get_healthy_instances(), and
get_services(); query methods have async_ counterparts. watch_service() pins a
loaded resource and forwards cache lifecycle events; unwatch_service() releases it.
from polaris.pkg.model.service import GetOneInstanceRequest
instance = consumer.get_one_instance(GetOneInstanceRequest(
namespace="default",
service="demo",
))
After invoking the downstream service, report the result with
update_service_call_result() or async_update_service_call_result().
Local cache behavior, idle eviction, disk retries, and restart recovery are covered by the examples and configuration reference.
- MCP, A2A, and LangGraph use ordinary
Instanceregistration and discovery. - Service contracts use
report_service_contract()andget_service_contract(). SkillAPIprovides read-only get/list/download operations over an independent connector.- Skill downloads can fall back to versioned local backups after network errors.
See AI Registry APIs and:
| Kind | Names |
|---|---|
| Server connector | grpc |
| Local cache | inmemory, file |
| Service router | isolatedRouter, metadataRouter, recoverRouter |
| Load balancer | weightedRandom, random |
| Circuit breaker | composite |
| Stat reporter | prometheus (pushgateway chain alias for push mode) |
| Event reporter | pushgateway |
Legacy names wr and err_count normalize to weightedRandom and composite.
Remote lossless rules are supported. Remote circuit-breaking, routing, rate-limiting and
configuration rules remain disabled, and active health detection is not enabled.
Public cloud currently uses Pushgateway as the default supported export path. Prometheus pull remains available for self-hosted or custom scraping setups. See Observability.
Each context has an isolated event center for implemented instance-cache and local circuit-breaker events, with an optional Pushgateway reporter. See Events.
The registry and Skill connectors support independent TLS and mTLS certificates. Invalid certificate configuration fails startup instead of falling back to plaintext. See TLS.
From the repository root, Quickstart reads its adjacent polaris.yaml:
export POLARIS_SERVER_ADDRESS=127.0.0.1:8091
export POLARIS_TOKEN=
make -C examples run DEMO=quickstart/provider ARGS='--service-token "" --port 0'
# Another terminal with the same environment
make -C examples run DEMO=quickstart/consumer ARGS='--port 18080'
--service-token is required; an empty string works when service authentication is
disabled. Runs stay in the foreground; use separate terminals or &.
make -C examples logs ARGS='--only quickstart --latest --tail 30'
make -C examples cleanup ARGS='--only quickstart --dry-run'
make -C examples cleanup ARGS='--only quickstart'
See examples/README.md for demos, Makefiles and log/cleanup options.
Verification and test artifacts belong to integration/:
./integration/verify.sh --only quickstart
./integration/verify_e2e.sh --only quickstart
See the integration guide and quickstart tests for checks and test artifacts.
Cloud E2E supports local deployment packaging, cloud execution, cloud log archiving, and local result import:
./examples/cloud-package.sh
./integration/cloud/import-logs.sh <returned-logs.tar.gz>
See cloud verification for the complete workflow.