> For the complete documentation index, see [llms.txt](https://govplane.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://govplane.gitbook.io/docs/documentation/sdk-for-javascript-node.js/python-sdk-beta.md).

# Python SDK \[Beta]

### Installation

Requires **Python 3.9+**. No external dependencies.

```bash
pip install "git+https://github.com/GovPlane/python-runtime-sdk.git"
```

***

### Quick start

```python
from govplane_sdk import RuntimeClient, RuntimeClientConfig, Target

config = (
    RuntimeClientConfig.builder(
        base_url="https://runtime.govplane.io",
        runtime_key="<GP_RUNTIME_KEY>",
    )
    .poll_ms(5_000)
    .build()
)

client = RuntimeClient(config)
client.warm_start()          # blocking — waits for first bundle (default 10 s)

decision = client.evaluate(
    Target("payments", "checkout", "create"),
    {"plan": "free", "country": "ES", "isAuthenticated": True, "role": "user"},
)

print(decision.get_decision())  # "allow" | "deny" | "throttle" | "kill_switch" | "custom"

client.flush_traces()
client.stop()
```

***

### Decision effects — precedence (highest → lowest)

| Priority | Effect          | Description                                 |
| -------- | --------------- | ------------------------------------------- |
| 1        | `kill_switch`   | Hard stop; overrides everything             |
| 2        | `deny`          | Explicit denial                             |
| 3        | `throttle`      | Rate limiting; selects the *strictest* rule |
| 4        | `allow`         | Permit                                      |
| 5        | `custom`        | Arbitrary JSON payload                      |
| —        | deny-by-default | No matching rule; always `deny`             |

***

### Configuration options

| Option                   | Default               | Description                                        |
| ------------------------ | --------------------- | -------------------------------------------------- |
| `poll_ms`                | `5000`                | Normal TTL between bundle polls (ms)               |
| `burst_poll_ms`          | `500`                 | Poll interval during incident burst mode (ms)      |
| `burst_duration_ms`      | `30000`               | How long burst mode lasts (ms)                     |
| `timeout_ms`             | `5000`                | HTTP request timeout (ms)                          |
| `backoff_base_ms`        | `500`                 | Initial backoff delay (ms)                         |
| `backoff_max_ms`         | `30000`               | Maximum backoff cap (ms)                           |
| `backoff_jitter`         | `0.2`                 | ±20% jitter on backoff delay                       |
| `degrade_after_failures` | `3`                   | Consecutive failures before status → `degraded`    |
| `validate_context`       | `True`                | Enforce `ContextPolicy` on every `evaluate()` call |
| `incident_env_flag`      | `GP_RUNTIME_INCIDENT` | Env var that activates burst mode                  |
| `incident_file_path`     | `None`                | File whose mtime change activates burst mode       |

***

### Evaluating with a trace

```python
from govplane_sdk import TraceOptions, TraceLevel

result = client.evaluate_with_trace(
    Target("payments", "checkout", "create"),
    {"plan": "enterprise", "country": "US"},
    TraceOptions.of_level(TraceLevel.Full),
)

print(result.decision.get_decision())

if result.trace is not None:
    winner = result.trace.get_winner()
    print(f"Policy: {winner.policy_key}, Rule: {winner.rule_id}")
```

***

### Environment variables

| Variable              | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `GP_RUNTIME_KEY`      | API key for the runtime bundle server                |
| `GP_RUNTIME_INCIDENT` | Set to any non-empty value to activate burst-polling |

***

### Notes on threading

`RuntimeClient` starts a background **daemon thread** for bundle polling. The thread stops automatically when the Python process exits because it is a daemon thread. Calling `client.stop()` signals it to stop gracefully.

`evaluate()` and `evaluate_with_trace()` are thread-safe — they read from an in-memory cache protected by a lock.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/sdk-for-javascript-node.js/python-sdk-beta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.