# Python reference (/docs/sdks/python)
The Python SDK runs on Python 3.9 and later. `Lynk` methods are async, and each has a `_sync` twin for code without an event loop. Results are typed models.

## Install [#install]

```bash
pip install docklee
```

```python
from docklee import Dock, Lynk
```

## Dock [#dock]

`Dock` writes into a container or a memory space. See [Configuration](/docs/sdks/configuration#dock-options) for its constructor options.

### `capture` [#capture]

Adds an event to the buffer and returns at once. Blank content is ignored, and identical content within 60 seconds is skipped.

```python
dock.capture(
    "Customer asked to move the renewal date to June.",
    type="event",
    metadata={"ticket_id": "T-4821"},
    end_user="user_8f2c",
)
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `str` | none | The text to store. |
| `type` | `str` | `"conversation"` | `conversation`, `document`, `event`, `preference`, `entity`, or `knowledge`. |
| `metadata` | `dict` | `None` | Your own key and value pairs. |
| `dedup_key` | `str` | `None` | Your own key for deciding when two captures are the same. |
| `end_user` | `str` | the `Dock` default | The person this memory belongs to. |

Returns `None`. Raises `RuntimeError` if the `Dock` is closed.

### `flush_sync` [#flush_sync]

Sends the buffer and waits. On failure, the events go back into the buffer for the next flush.

```python
result = dock.flush_sync()
if result is not None:
    print(result.accepted, result.rejected)
```

Returns a [`DockIngestResult`](/docs/sdks/types#dockingestresult), or `None` when the buffer was empty or the request failed.

### `flush` [#flush]

The async form of `flush_sync`. It raises on failure instead of returning `None`.

```python
result = await dock.flush()
```

### `close` [#close]

Sends the buffer, closes connections, and stops the `Dock` from accepting more captures.

```python
await dock.close()
```

### `instrument` [#instrument]

Attaches a middleware to a FastAPI, Starlette, or other Starlette-based app that captures write requests. See [Instrument your app](/docs/memory/automatic-capture/instrument).

```python
dock.instrument(app)
```

### `watch` [#watch]

Starts a background thread that captures new and changed rows from database tables. See [Watch a database](/docs/memory/automatic-capture/watch).

```python
dock.watch(connection_string=os.environ["ORDERS_DATABASE_URL"], tables=["orders"])
```

| Parameter | Type | Default |
| --- | --- | --- |
| `connection_string` | `str` | none |
| `tables` | `list[str]` | none |
| `poll_interval` | `int` | `5` |
| `capture_inserts` | `bool` | `True` |
| `capture_updates` | `bool` | `True` |

### `listen` [#listen]

Starts a background thread that receives webhooks and captures them. See [Listen for webhooks](/docs/memory/automatic-capture/listen).

```python
dock.listen(port=8080, secret=os.environ["WEBHOOK_SIGNING_SECRET"])
```

| Parameter | Type | Default |
| --- | --- | --- |
| `port` | `int` | `8080` |
| `parsers` | `dict[str, str]` | `None` |
| `secret` | `str` | `None` |

## Lynk [#lynk]

`Lynk` reads from an engine or a memory space. See [Configuration](/docs/sdks/configuration#lynk-options) for its constructor options.

### `query` and `query_sync` [#query-and-query_sync]

Asks an engine a question and returns a cited answer. See [Query an engine](/docs/knowledge/query-an-engine).

```python
result = await lynk.query("What is the refund window?")
result = lynk.query_sync("What is the refund window?", mode="blended")
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `str` | none | The question. |
| `engine_id` | `str` | the `Lynk` default | The engine to ask. |
| `top_k` | `int` | `8` | Chunks to search for, from 1 to 50. |
| `mode` | `str` | `"precise"` | See [Answer modes](/docs/knowledge/answers/answer-modes). |
| `stream` | `bool` | `False` | `query` only. Returns an async iterator of answer text. |

Returns a [`KnowledgeResult`](/docs/sdks/types#knowledgeresult), or an async iterator of `str` when `stream=True`. Raises `ValueError` when no engine ID is set.

```python
stream = await lynk.query("Summarize the refund policy.", stream=True)
async for token in stream:
    print(token, end="", flush=True)
```

### `retrieve` and `retrieve_sync` [#retrieve-and-retrieve_sync]

Returns the ranked chunks for a question, without writing an answer. See [Retrieve context](/docs/knowledge/retrieve-context).

```python
chunks = lynk.retrieve_sync("refund window", top_k=5)
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `question` | `str` | none | The question. |
| `engine_id` | `str` | the `Lynk` default | The engine to search. |
| `top_k` | `int` | `8` | Chunks to return, from 1 to 100. |

Returns a list of [`KnowledgeChunk`](/docs/sdks/types#knowledgechunk). Raises `ValueError` when no engine ID is set.

### `recall` and `recall_sync` [#recall-and-recall_sync]

Returns the memories that answer a question. See [Recall memory](/docs/memory/recall-memory).

```python
records = lynk.recall_sync("display preferences", end_user="user_8f2c")
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | `str` | none | The question. |
| `memory_space_id` | `str` | the `Lynk` default | The space to read. |
| `top_k` | `int` | `5` | Memories to return, from 1 to 50. |
| `end_user` | `str` | the `Lynk` default | Returns only this person's memories. |

Returns a list of [`MemoryRecord`](/docs/sdks/types#memoryrecord). Raises `ValueError` when no memory space ID is set.

### `close` [#close-1]

Closes connections.

```python
await lynk.close()
```

## Logging [#logging]

The SDK logs through the standard `logging` module, under `docklee.dock`, `docklee.lynk`, and `docklee.http`. Turn on debug logging to see retries and skipped duplicates:

```python
import logging

logging.getLogger("docklee").setLevel(logging.DEBUG)
```

## Next steps [#next-steps]

You've seen every Python method. See the shapes they return next.

<Cards>
  <Card title="Types" href="/docs/sdks/types" description="Every result and its fields." />
  <Card title="Errors and retries" href="/docs/sdks/errors-and-retries" description="What's retried, and what's raised." />
  <Card title="Configuration" href="/docs/sdks/configuration" description="Every constructor option." />
</Cards>
