Polaris Python SDK

中文

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.

Install

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.

Configure

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

Context

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.

Provider

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.

Consumer

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.

AI Registry

• MCP, A2A, and LangGraph use ordinary Instance registration and discovery.
• Service contracts use report_service_contract() and get_service_contract().
• SkillAPI provides 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:

• MCP example
• A2A example
• Skill example

Plugins

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.

Observability And Security

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.

Examples

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.

License

BSD 3-Clause