# Python

Connect a Python workflow using the package clients or an explicit HTTP request with the required capability.

Source: https://docs.minds.sh/docs/developers/python



The Python package is `akasha-sdk`, imported as `akasha`. The checked-in manifest requires Python 3.10 or later. Its client uses synchronous `httpx`; the presence of async test dependencies does not make this an async client.

## Install [#install]

```bash
python -m pip install akasha-sdk
```

Use your configured package registry. To work directly from source, run `python -m pip install -e ./minds-python-sdk` from the Akasha repository root. Publication of the registry version is separate from the local source inventory.

## First request with the current instance contract [#first-request-with-the-current-instance-contract]

The package depends on `httpx`. Use its request directly when you need a capability header and the exact daemon tool envelope:

```python
import os
import httpx

with httpx.Client(
    base_url=os.environ['MINDS_INSTANCE_URL'],
    headers={'x-akasha-capability': os.environ['MINDS_CAPABILITY']},
    timeout=30.0,
) as http:
    response = http.post('/v1/mcp/tools/call', json={
        'name': 'recall',
        'arguments': {'query': 'launch review', 'limit': 5},
    })
    response.raise_for_status()
    output = response.json()
    if output.get('is_error'):
        raise RuntimeError('Recall failed')
    print(output.get('result', {}).get('memories', []))
```

This is an explicit HTTP example, not a call to a currently compatible `brain.recall` convenience method.

## Client organization [#client-organization]

`AkashaClient(base_url, api_key, timeout=30.0, max_retries=3, verify_ssl=True)` provides `control_plane` and `runtime(instance_url)`. A runtime client exposes core, KV, graph, vector, analytics, memory, ML, SNN, neurosymbolic, continual, MHN, and cognitive clients.

The main client's `api_key` is sent as `Authorization: Bearer ...`. It does not populate `x-api-key` for the management service or `x-akasha-capability` for a capability-required instance. A public `RuntimeClient(http_client)` can accept an explicitly configured `httpx.Client`, but method payload compatibility still needs checking.

Use a context manager or close the client after use. The exported exception classes distinguish authentication, authorization, validation, not-found, rate-limit, timeout, connection, and server failures. Those exceptions depend on the call path; direct `httpx` requests use `httpx` errors.

## Important contract differences [#important-contract-differences]

The current hybrid retrieval wrapper sends `query` and expects `results`; the daemon accepts `text` and returns `rows`. Episodic search returns an array in the daemon, while the Python wrapper expects an `events` envelope. See [Compatibility](/docs/developers/compatibility) for exact differences before treating an empty SDK result as an empty Mind.

The [complete Python reference](/docs/developers/reference/python) lists public classes, models, properties, method parameters, and return annotations from all package modules.