reference.md

# Reference
## Agent
<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">create</a>(...) -> AgentResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new PhenoAgent with specified configuration
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.create(
    name="Medical Assistant",
    description="An AI assistant for medical information processing",
    prompts=[
        "prompt_123"
    ],
    tags=[
        "medical",
        "fhir"
    ],
    provider="7002b0b4-8d09-445a-bf65-0fafdaf26c35",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request:** `AgentCreateRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">list</a>(...) -> ListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a list of PhenoAgents belonging to the authenticated user
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.list(
    tags="tags",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**tags:** `typing.Optional[str]` — Filter by tags
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">get</a>(...) -> AgentResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a specific agent by its ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.get(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">update</a>(...) -> AgentResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing agent's configuration
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.update(
    id="id",
    name="Medical Assistant",
    description="Updated description for the medical assistant",
    prompts=[
        "prompt_123"
    ],
    tags=[
        "medical",
        "fhir",
        "updated"
    ],
    provider="7002b0b4-8d09-445a-bf65-0fafdaf26c35",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**request:** `AgentCreateRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes an existing agent
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.delete(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.<a href="src/phenoml/agent/client.py">patch</a>(...) -> AgentResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Patches an existing agent's configuration
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.agent import JsonPatchOperation

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.patch(
    id="id",
    request=[
        JsonPatchOperation(
            op="replace",
            path="/description",
            value="patched description",
        ),
        JsonPatchOperation(
            op="add",
            path="/tags/-",
            value="updated",
        )
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Agent ID
    
</dd>
</dl>

<dl>
<dd>

**request:** `JsonPatch` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Chat
<details><summary><code>client.agent.chat.<a href="src/phenoml/agent/chat/client.py">send</a>(...) -> AgentChatResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Send a message to an agent and receive a JSON response.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.send(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    message="What is the patient\'s current condition?",
    session_id="session-abc123",
    agent_id="agent-123",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**message:** `str` — The message to send to the agent
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `str` — The ID of the agent to chat with
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**context:** `typing.Optional[str]` — Optional context for the conversation
    
</dd>
</dl>

<dl>
<dd>

**session_id:** `typing.Optional[str]` — Optional session ID for conversation continuity. Only one request may be active for a session at a time; overlapping turns for the same session return 409 Conflict.
    
</dd>
</dl>

<dl>
<dd>

**enhanced_reasoning:** `typing.Optional[bool]` — Enable enhanced reasoning capabilities. Increases latency but improves response quality and reliability.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.chat.<a href="src/phenoml/agent/chat/client.py">stream</a>(...) -> typing.Iterator[bytes]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Send a message to an agent and receive the response as a Server-Sent Events
(SSE) stream. Events include message_start, content_delta, tool_use,
tool_result, message_end, and error.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.stream(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    message="What is the patient\'s current condition?",
    session_id="session-abc123",
    agent_id="agent-123",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**message:** `str` — The message to send to the agent
    
</dd>
</dl>

<dl>
<dd>

**agent_id:** `str` — The ID of the agent to chat with
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**context:** `typing.Optional[str]` — Optional context for the conversation
    
</dd>
</dl>

<dl>
<dd>

**session_id:** `typing.Optional[str]` — Optional session ID for conversation continuity. Only one request may be active for a session at a time; overlapping turns for the same session return 409 Conflict.
    
</dd>
</dl>

<dl>
<dd>

**enhanced_reasoning:** `typing.Optional[bool]` — Enable enhanced reasoning capabilities. Increases latency but improves response quality and reliability.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.chat.<a href="src/phenoml/agent/chat/client.py">list_messages</a>(...) -> ListMessagesResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a list of chat messages for a given chat session
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.chat.list_messages(
    chat_session_id="chat_session_id",
    num_messages=1,
    role="user",
    order="asc",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**chat_session_id:** `str` — Chat session ID
    
</dd>
</dl>

<dl>
<dd>

**num_messages:** `typing.Optional[int]` — Number of messages to return
    
</dd>
</dl>

<dl>
<dd>

**role:** `typing.Optional[ListMessagesRequestRole]` 

Filter by one or more message roles. Multiple roles can be specified as a comma-separated string.
If not specified, messages with all roles are returned.

**Available roles:**
- `user` - Messages from the user
- `assistant` - Text responses from the AI assistant
- `model` - Function/tool call requests from the model
- `function` - Function/tool call results
    
</dd>
</dl>

<dl>
<dd>

**order:** `typing.Optional[ListMessagesRequestOrder]` — Order of messages
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Agent Prompts
<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">create</a>(...) -> AgentPromptsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new agent prompt
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.create(
    name="Medical Assistant System Prompt",
    description="System prompt for medical assistant agent",
    content="You are a helpful medical assistant specialized in FHIR data processing.",
    is_default=False,
    tags=[
        "medical",
        "system"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Prompt name
    
</dd>
</dl>

<dl>
<dd>

**content:** `str` — Prompt content
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Prompt description
    
</dd>
</dl>

<dl>
<dd>

**is_default:** `typing.Optional[bool]` — Whether this is a default prompt
    
</dd>
</dl>

<dl>
<dd>

**tags:** `typing.Optional[typing.List[str]]` — Tags for categorizing the prompt
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">list</a>() -> PromptsListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a list of agent prompts belonging to the authenticated user
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">get</a>(...) -> AgentPromptsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a specific prompt by its ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.get(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Prompt ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">update</a>(...) -> AgentPromptsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing prompt
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.update(
    id="id",
    name="Medical Assistant System Prompt",
    description="Updated system prompt",
    content="You are a helpful medical assistant. Always cite ICD-10 codes when discussing diagnoses.",
    is_default=False,
    tags=[
        "medical",
        "system",
        "updated"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Prompt ID
    
</dd>
</dl>

<dl>
<dd>

**name:** `typing.Optional[str]` — Prompt name
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Prompt description
    
</dd>
</dl>

<dl>
<dd>

**content:** `typing.Optional[str]` — Prompt content
    
</dd>
</dl>

<dl>
<dd>

**is_default:** `typing.Optional[bool]` — Whether this is a default prompt
    
</dd>
</dl>

<dl>
<dd>

**tags:** `typing.Optional[typing.List[str]]` — Tags for categorizing the prompt
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">delete</a>(...) -> PromptsDeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a prompt
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.delete(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Prompt ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.agent.prompts.<a href="src/phenoml/agent/prompts/client.py">patch</a>(...) -> AgentPromptsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Patches an existing prompt
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.agent import JsonPatchOperation

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.agent.prompts.patch(
    id="id",
    request=[
        JsonPatchOperation(
            op="replace",
            path="/content",
            value="Updated prompt content.",
        )
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Agent Prompt ID
    
</dd>
</dl>

<dl>
<dd>

**request:** `JsonPatch` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Authtoken
<details><summary><code>client.authtoken.<a href="src/phenoml/authtoken/client.py">get_token</a>(...) -> TokenResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

OAuth 2.0 client credentials token endpoint (RFC 6749 §4.4).
Accepts client_id and client_secret in the request body (JSON or
form-encoded) or via Basic Auth header (RFC 6749 §2.3.1), and
returns an access token with token expiration information.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.authtoken.get_token(
    client_id="your_client_id",
    client_secret="your_client_secret",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**grant_type:** `typing.Optional[str]` — Must be "client_credentials" if provided
    
</dd>
</dl>

<dl>
<dd>

**client_id:** `typing.Optional[str]` — The client ID (credential username)
    
</dd>
</dl>

<dl>
<dd>

**client_secret:** `typing.Optional[str]` — The client secret (credential password)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Cohort
<details><summary><code>client.cohort.<a href="src/phenoml/cohort/client.py">analyze</a>(...) -> CohortResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language text into structured FHIR search queries for patient cohort analysis
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.cohort.analyze(
    text="female patients over 65 with diabetes but not hypertension",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text describing patient cohort criteria
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Code Systems
<details><summary><code>client.construe.code_systems.<a href="src/phenoml/construe/code_systems/client.py">upload</a>(...) -> UploadResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan.
Returns 202 immediately; embedding generation runs asynchronously. Poll
GET /construe/codes/systems/{codesystem}?version={version} to check when status
transitions from "processing" to "ready" or "failed".
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import CodeResponse

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.upload(
    name="CUSTOM_CODES",
    version="1.0",
    format="json",
    codes=[
        CodeResponse(
            code="X001",
            description="Example custom code 1",
        ),
        CodeResponse(
            code="X002",
            description="Example custom code 2",
        )
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` 

Name of the code system. Names are case-insensitive and stored uppercase.
Builtin system names (e.g. ICD-10-CM, SNOMED_CT_US_LITE, LOINC, CPT, etc.) are
reserved and cannot be used for custom uploads; attempts return HTTP 403 Forbidden.
    
</dd>
</dl>

<dl>
<dd>

**version:** `str` — Version of the code system
    
</dd>
</dl>

<dl>
<dd>

**format:** `UploadRequestFormat` — Upload format
    
</dd>
</dl>

<dl>
<dd>

**revision:** `typing.Optional[float]` — Optional revision number
    
</dd>
</dl>

<dl>
<dd>

**file:** `typing.Optional[str]` 

The file contents as a base64-encoded string.
For CSV format, this is the CSV file contents.
For JSON format, this is a base64-encoded JSON array; prefer using 'codes' instead.
    
</dd>
</dl>

<dl>
<dd>

**code_col:** `typing.Optional[str]` — Column name containing codes (required for CSV format)
    
</dd>
</dl>

<dl>
<dd>

**desc_col:** `typing.Optional[str]` — Column name containing descriptions (required for CSV format)
    
</dd>
</dl>

<dl>
<dd>

**defn_col:** `typing.Optional[str]` — Optional column name containing long definitions (for CSV format)
    
</dd>
</dl>

<dl>
<dd>

**codes:** `typing.Optional[typing.List[CodeResponse]]` 

The codes to upload as a JSON array (JSON format only).
This is the preferred way to upload JSON codes, as it avoids unnecessary base64 encoding.
If both 'codes' and 'file' are provided, 'codes' takes precedence.
    
</dd>
</dl>

<dl>
<dd>

**replace:** `typing.Optional[bool]` 

If true, replaces an existing code system with the same name and version.
Builtin systems cannot be replaced; attempts to do so return HTTP 403 Forbidden.
When false (default), uploading a duplicate returns 409 Conflict.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.code_systems.<a href="src/phenoml/construe/code_systems/client.py">list</a>() -> ListCodeSystemsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.code_systems.<a href="src/phenoml/construe/code_systems/client.py">find</a>(...) -> GetCodeSystemDetailResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns full metadata for a single code system, including timestamps and builtin status.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.find(
    codesystem="ICD-10-CM",
    version="2025",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name (e.g., "ICD-10-CM", "SNOMED_CT_US_LITE")
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the code system, such as `umls-2026aa`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.code_systems.<a href="src/phenoml/construe/code_systems/client.py">delete</a>(...) -> DeleteCodeSystemResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a custom (non-builtin) code system and all its codes. Builtin systems cannot be deleted.
Only available on dedicated instances. Large systems may take up to a minute to delete.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.delete(
    codesystem="CUSTOM_CODES",
    version="version",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the custom code system.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.code_systems.<a href="src/phenoml/construe/code_systems/client.py">export</a>(...) -> ExportCodeSystemResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Exports a custom (non-builtin) code system as a JSON file compatible with the upload format.
The exported file can be re-uploaded directly via POST /construe/upload with format "json".
Only available on dedicated instances. Builtin systems cannot be exported.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.code_systems.export(
    codesystem="CUSTOM_CODES",
    version="version",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the custom code system.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Construe
<details><summary><code>client.construe.<a href="src/phenoml/construe/client.py">submit_feedback</a>(...) -> FeedbackResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Submits user feedback on results from the Construe extraction endpoint.
Feedback includes the full extraction result received and the result the user expected.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import ExtractCodesResult, ExtractRequestSystem, ExtractedCodeResult

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.submit_feedback(
    text="Patient has type 2 diabetes with hyperglycemia",
    received_result=ExtractCodesResult(
        system=ExtractRequestSystem(
            name="ICD-10-CM",
            version="2025",
        ),
        codes=[
            ExtractedCodeResult(
                code="E11.9",
                description="Type 2 diabetes mellitus without complications",
                valid=True,
            )
        ],
    ),
    expected_result=ExtractCodesResult(
        system=ExtractRequestSystem(
            name="ICD-10-CM",
            version="2025",
        ),
        codes=[
            ExtractedCodeResult(
                code="E11.65",
                description="Type 2 diabetes mellitus with hyperglycemia",
                valid=True,
            )
        ],
    ),
    detail="Expected code E11.65 because the text mentions hyperglycemia",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — The natural language text that was used for code extraction
    
</dd>
</dl>

<dl>
<dd>

**received_result:** `ExtractCodesResult` 
    
</dd>
</dl>

<dl>
<dd>

**expected_result:** `ExtractCodesResult` 
    
</dd>
</dl>

<dl>
<dd>

**detail:** `typing.Optional[str]` — Optional details explaining the feedback
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Codes
<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">extract</a>(...) -> ExtractCodesResult</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language text into structured medical codes.

Pass `system.version` to select a specific code system version, for example
`umls-2026aa` for UMLS 2026AA-backed systems.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import ExtractRequestSystem

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.extract(
    text="Patient is a 14-year-old female, previously healthy, who is here for evaluation of abnormal renal ultrasound with atrophic right kidney.",
    system=ExtractRequestSystem(
        name="ICD-10-CM",
        version="2025",
    ),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text to extract codes from
    
</dd>
</dl>

<dl>
<dd>

**system:** `typing.Optional[ExtractRequestSystem]` 
    
</dd>
</dl>

<dl>
<dd>

**config:** `typing.Optional[ExtractRequestConfig]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">phenocr</a>(...) -> ExtractCodesResult</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

**Alpha:** phenocr is an alpha feature. Request parameters, response
shape, and results may change between releases. Do not depend on it for
production workloads yet.

Extracts medical codes from natural language clinical text using phenocr.

Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The
code system name and version are both required.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.construe import PhenocrExtractRequestSystem

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.phenocr(
    text="5-year-old male with seizures, severe intellectual disability, microcephaly, and hypotonia.",
    system=PhenocrExtractRequestSystem(
        name="HPO",
        version="umls-2026AA",
    ),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text to extract codes from
    
</dd>
</dl>

<dl>
<dd>

**system:** `PhenocrExtractRequestSystem` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">crosswalk</a>(...) -> CrosswalkResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Maps one source medical code to one or more target code-system URIs using
shared UMLS CUIs. A successful response is HTTP 200 even when the source
code or a target has no matches; inspect `reason_code` on the item and
target entries for miss details.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.crosswalk(
    system="http://hl7.org/fhir/sid/icd-10-cm",
    code="A02.24",
    targets=[
        "http://human-phenotype-ontology.org"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**system:** `str` — Source FHIR code-system URI.
    
</dd>
</dl>

<dl>
<dd>

**code:** `str` — Source code to map.
    
</dd>
</dl>

<dl>
<dd>

**targets:** `typing.List[str]` — Target FHIR code-system URIs.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">list</a>(...) -> ListCodesResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a paginated list of all codes in the specified code system.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.list(
    codesystem="ICD-10-CM",
    version="2025",
    cursor="cursor",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name (e.g., "ICD-10-CM", "SNOMED_CT_US_LITE")
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the code system, such as `umls-2026aa`.
    
</dd>
</dl>

<dl>
<dd>

**cursor:** `typing.Optional[str]` — Pagination cursor from previous response
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of codes to return (default 20)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">lookup</a>(...) -> GetCodeResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Looks up a specific code and returns its details.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.lookup(
    codesystem="ICD-10-CM",
    code_id="E1165",
    version="version",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name
    
</dd>
</dl>

<dl>
<dd>

**code_id:** `str` 

The code identifier. ICD-10-CM codes are stored without their
cosmetic dot (use "E1165", not "E11.65").
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the code system, such as `umls-2026aa`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">search_semantic</a>(...) -> SemanticSearchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Performs semantic similarity search using vector embeddings.

**Availability**: This endpoint works for both **built-in and custom** code systems.

**When to use**: Best for natural language queries where you want to find conceptually
related codes, even when different terminology is used. The search understands meaning,
not just keywords.

**Examples**:
- Query "trouble breathing at night" finds codes like "Sleep apnea", "Orthopnea",
  "Nocturnal dyspnea" — semantically related but no exact keyword matches
- Query "heart problems" finds "Myocardial infarction", "Cardiac arrest", "Arrhythmia"

**Trade-offs**: Slower than text search (requires embedding generation), but finds
conceptually similar results that keyword search would miss.

See also: `/search/text` for faster keyword-based lookup with typo tolerance.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.search_semantic(
    codesystem="ICD-10-CM",
    text="patient has trouble breathing at night and wakes up gasping",
    version="version",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name
    
</dd>
</dl>

<dl>
<dd>

**text:** `str` — Natural language text to find semantically similar codes for
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the code system, such as `umls-2026aa`.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results (default 10, max 50)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.construe.codes.<a href="src/phenoml/construe/codes/client.py">search_text</a>(...) -> TextSearchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Performs fast full-text search over code IDs and descriptions.

**Availability**: This endpoint is only available for **built-in code systems**.
Custom code systems uploaded via `/construe/upload` are not indexed for full-text search
and will return empty results. Use `/search/semantic` to search custom code systems.

**When to use**: Best for autocomplete UIs, code lookup, or when users know part of
the code ID or specific keywords. Fast response times suitable for typeahead interfaces.

**Features**:
- Substring matching on code IDs (e.g., "11.65" finds "E11.65")
- Typo tolerance on descriptions (not on code IDs)
- Fast response times (~10-50ms)

**Examples**:
- Query "E11" finds all codes starting with E11 (diabetes codes)
- Query "diabtes" (typo) still finds "diabetes" codes

**Trade-offs**: Faster than semantic search, but only matches keywords/substrings.
Won't find conceptually related codes with different terminology.

See also: `/search/semantic` for finding conceptually similar codes.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.construe.codes.search_text(
    codesystem="ICD-10-CM",
    q="E11.65",
    version="version",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**codesystem:** `str` — Code system name
    
</dd>
</dl>

<dl>
<dd>

**q:** `str` — Search query (searches code IDs and descriptions)
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — Specific version of the code system, such as `umls-2026aa`.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Maximum number of results (default 20, max 100)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Fhir
<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">search</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves FHIR resources from the specified provider. Supports both individual resource retrieval (e.g. `Patient/123` via the path) and search operations.

FHIR search parameters are passed through to the upstream server verbatim as native query-string parameters; this proxy does not model, validate, or transform them. Append standard FHIR search parameters directly to the request URL. Supported parameters include:
- Resource-specific search parameters (e.g. `name` for Patient, `status` for Observation)
- Common search parameters (`_id`, `_lastUpdated`, `_tag`, `_profile`, `_security`, `_text`, `_content`, `_filter`)
- Result parameters (`_count`, `_offset`, `_sort`, `_include`, `_revinclude`, `_summary`, `_elements`)
- Search prefixes for dates, numbers, and quantities (`eq`, `ne`, `gt`, `ge`, `lt`, `le`, `sa`, `eb`, `ap`)

Examples:
- `Patient?name=John%20Doe&_count=10&_sort=family`
- `Observation?patient=Patient/123&date=ge2023-01-01&category=vital-signs&_sort=-date`

When using a generated SDK, supply these via the client's request-level query-parameter option (the SDK escape hatch) rather than a typed argument.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.search(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**fhir_path:** `str` 

The FHIR resource path to operate on. This follows FHIR RESTful API conventions.
Examples:
- "Patient" (for resource type operations)
- "Patient/123" (for specific resource operations)
- "Patient/123/_history" (for history operations)
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">create</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new FHIR resource on the specified provider. The request body should contain a valid FHIR resource in JSON format.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.create(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Patient"},
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**fhir_path:** `str` 

The FHIR resource path to operate on. This follows FHIR RESTful API conventions.
Examples:
- "Patient" (for resource type operations)
- "Patient/123" (for specific resource operations)
- "Patient/123/_history" (for history operations)
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Any` 
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">upsert</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates or updates a FHIR resource on the specified provider. If the resource exists, it will be updated; otherwise, it will be created.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.upsert(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Patient", "id": "123"},
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**fhir_path:** `str` 

The FHIR resource path to operate on. This follows FHIR RESTful API conventions.
Examples:
- "Patient" (for resource type operations)
- "Patient/123" (for specific resource operations)
- "Patient/123/_history" (for history operations)
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Any` 
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">delete</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a FHIR resource from the specified provider.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.delete(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**fhir_path:** `str` 

The FHIR resource path to operate on. This follows FHIR RESTful API conventions.
Examples:
- "Patient" (for resource type operations)
- "Patient/123" (for specific resource operations)
- "Patient/123/_history" (for history operations)
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">patch</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Partially updates a FHIR resource on the specified provider.

Two body formats are supported, selected by request content type:
- `application/json-patch+json` — an array of JSON Patch operations as defined in RFC 6902. Each operation specifies:
  - `op`: The operation type (add, remove, replace, move, copy, test)
  - `path`: JSON Pointer to the target location in the resource
  - `value`: The value to use (required for add, replace, and test operations)
- `application/fhir+json` — a partial FHIR resource for merge-patch semantics.

**Note:** This proxy currently forwards the request body to the upstream FHIR server with `Content-Type: application/fhir+json` regardless of the declared request content type. JSON Patch (RFC 6902) therefore only succeeds against upstream servers that accept patch arrays under `application/fhir+json`; servers that strictly enforce patch media types may reject or misinterpret it. Support for either format ultimately depends on the upstream FHIR server.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir import PatchRequestBodyItem

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.patch(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    fhir_path="Patient",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request=[
        PatchRequestBodyItem(
            op="replace",
            path="/name/0/family",
            value="NewFamilyName",
        )
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**fhir_path:** `str` 

The FHIR resource path to operate on. This follows FHIR RESTful API conventions.
Examples:
- "Patient" (for resource type operations)
- "Patient/123" (for specific resource operations)
- "Patient/123/_history" (for history operations)
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.List[PatchRequestBodyItem]` — Array of JSON Patch operations following RFC 6902
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir.<a href="src/phenoml/fhir/client.py">execute_bundle</a>(...) -> typing.Any</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Executes a FHIR Bundle transaction or batch operation on the specified provider. This allows multiple FHIR resources to be processed in a single request.

The request body should contain a valid FHIR Bundle resource with transaction or batch type.

The request is proxied to the configured FHIR server with appropriate authentication headers.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir.execute_bundle(
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    request={"resourceType": "Bundle", "type": "transaction", "entry": [{"request": {"method": "POST", "url": "Patient"}, "resource": {"resourceType": "Patient", "name": [{"family": "Doe", "given": ["John"]}]}}, {"request": {"method": "POST", "url": "Observation"}, "resource": {"resourceType": "Observation", "status": "final", "subject": {"reference": "Patient/123"}}}]},
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` 

The ID of the FHIR provider to use. Can be either:
- A UUID representing the provider ID
- A provider name (legacy support - will just use the most recently updated provider with this name)
    
</dd>
</dl>

<dl>
<dd>

**request:** `typing.Any` 
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Fhir2Omop
<details><summary><code>client.fhir2omop.<a href="src/phenoml/fhir2omop/client.py">create</a>(...) -> CreateOmopResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows,
grouped by destination table in `tables`. Uncertain-status and unresolved-
primary-concept clinical rows stay in those tables and are identified by
the optional `rows_for_review` index for consumer review and filtering.
Status-based retention covers uncertain supplied Condition verification,
unknown/missing/unreadable Encounter status, and explicit `unknown` status
on MedicationStatement, Observation, and Procedure. Other status exclusions
follow the resource-specific eligibility policy below.

Set `vocab_version` to select the OMOP vocabulary release used for coded
and inferred concept resolution. If omitted or empty, the API uses its
default release. The response's `vocab_version`, when present, identifies
the release used. Specify a release explicitly when reproducibility matters.

Supported concept fields use semantic mapping for text-only inputs and
unresolved source codings, with whole-term equivalence validation.
CodeableConcept text takes precedence over coding display. A single
equivalent suggestion must be validated before a real OMOP concept ID is
returned. The suggested vocabulary/code must
itself be an active standard concept valid for the destination; broader
crosswalk targets are not accepted for inferred suggestions.
Deterministic mappings take precedence; ambiguous or domain-mismatched
deterministic results are not reinterpreted. Units, routes, visits,
demographics, and collection sites use their field-specific resolution
policies. Semantic mapping returns MAPPED with a real concept ID on
success, or UNMAPPED with concept ID 0 when no standard concept is
selected. A bare code is not treated as a description. No source coding
is invented.

Contextual allergy finding decisions follow their dedicated policy and
are not replaced by description-based mapping.

Every inferred mapping has
`mappings.resolution.semantic_mapping.status: MAPPED`, with the OMOP
vocabulary release. Filter linked rows using the mapping's table/row ID
to exclude inferred results.
Original source coding and clinical-status eligibility are preserved.
For clinical rows covered by `rows_for_review`, successful inference
does not remove uncertain-status rows from the index; unresolved primary
concepts also remain indexed.
All shaped rows appear once in `tables`.

Standards basis: [FHIR R4 (v4.0.1)](https://hl7.org/fhir/R4/) defines
the accepted source elements and [OMOP CDM
v5.4](https://ohdsi.github.io/CommonDataModel/cdm54.html) defines the
output columns. The published [Vulcan FHIR-to-OMOP IG
v1.0.0](https://hl7.org/fhir/uv/omop/) is an informative FHIR R5
baseline; this endpoint documents and implements the equivalent R4
source elements, rather than accepting R5-only fields.

This response is a mapping result, not a complete CDM load pipeline.
When a source cannot supply a field that CDM v5.4 requires, the row is
still returned with that field unset; the value is not inferred. Common
cases are `year_of_birth` without a usable `birthDate`,
`drug_exposure_end_date` without an explicit end or single-event timing,
and a required event date (such as `condition_start_date`,
`procedure_date`, or `death_date`) whose source has no timing with at
least day precision. Apply your own policy to such rows before loading
them into a strictly conformant CDM instance.

Current resource coverage:
- `Patient` -> `person`; `deceased[x]` can also produce `death`, the
  first address can produce `location`, and more than one supplied race
  produces `observation` race rows (see Patient demographics below)
- `observation_period` -> one request-local derived row per person,
  spanning dates from that person's visit and clinical rows not listed
  in `rows_for_review`, plus Specimen and Death rows. Source end dates
  contribute even when the output table has no end column. No period
  row is returned for a person without qualifying dates; this is not
  enrollment or capture-completeness evidence
- `Location` -> `location` and `care_site`
- `Organization` -> `care_site`; its first address can produce `location`
- `HealthcareService` -> `care_site`
- `Practitioner` and `PractitionerRole` -> `provider`
- `Encounter` -> `visit_occurrence`
- `Specimen` -> `specimen`, with an explicit Patient subject; missing
  collection date or material retains a partial row with diagnostics
- `DeviceUseStatement` -> `device_exposure`, using referenced `Device.type`
- `Condition` -> domain-selected clinical table; default `condition_occurrence`
- `Procedure` -> domain-selected clinical table; default `procedure_occurrence`
- `MedicationRequest`, `MedicationStatement`, `MedicationAdministration`, and
  `MedicationDispense` -> domain-selected clinical table; default `drug_exposure`
- `Immunization` -> domain-selected clinical table; default `drug_exposure`
- `Observation` -> domain-selected clinical table. Numeric values prefer
  `measurement` and other values prefer `observation` when the code is
  valid for both tables.
  If no supported standard concept is selected, numeric values retain the
  `measurement` default and nonnumeric values retain `observation`.
- `AllergyIntolerance` -> `observation` for supported contextual
  allergy/intolerance mappings; other coded statements use domain-based
  placement excluding `drug_exposure` and `device_exposure`; default `observation`

Clinical placement follows the informative Vulcan IG's vocabulary-driven
domain assignment. Supported destinations are `condition_occurrence`,
`procedure_occurrence`, `drug_exposure`, `device_exposure`, `measurement`, and `observation`.
Resolved clinical records are returned in the table corresponding to the
domain of their mapped OMOP standard concept. The source resource
determines eligibility, field values, and the default table when no
supported mapping is available.
`AllergyIntolerance` records do not produce `drug_exposure` or
`device_exposure` rows. Device placement requires eligible use evidence:
prescriptions, uncertain diagnoses, and explicit negative Observation
results (false, SNOMED Negative, Known absent, or No, or interpretation
code `NEG` from
`http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation`)
do not accept Device placement, even when other supplied values are positive.
A recorder, asserter, or information source is retained as context rather
than treated as the device event's provider.

Coded `AllergyIntolerance.code` statements are interpreted using their
original codings, optional `type`, and `category`. Supported substances
produce an Observation finding separately from the causative substance
in `value_as_concept_id`. Drug-domain substances are valid values and do
not imply drug exposure or medication allergy. The finding is selected
by an explicit mapping policy, not a published substance-to-finding
crosswalk. Contextual findings report `MAPPED`,
`resolution.via: CONTEXTUAL`. `observation_source_concept_id` retains
the known OMOP identity of the original coding written to
`observation_source_value`, including when the finding is unresolved;
it is `0` when no source identity is known. The configured finding is
never substituted for the original source concept.

This adapts the informative R5 [Vulcan Value-as-Concept
pattern](https://hl7.org/fhir/uv/omop/INFORMATIVE1/en/ValueAsConceptPattern.html)
to R4's substance/product codes, optional `type`, and repeating `category`.
It selects a contextual finding and resolves the substance separately;
published `Maps to value` decomposition of a composite finding is not performed.

For `type: allergy`, medication (optionally with biologic) maps to
Allergy to drug (`439224`); other category sets use Allergic disposition
(`43530807`). For `type: intolerance`, medication (optionally biologic)
uses Intolerance to drug (`4240582`), food alone uses Intolerance to food
(`4340252`), and other sets use Intolerance to substance (`36684107`).
All selected concepts must be active and standard in the requested
vocabulary release. Limited reviewed substance mappings can derive an
absent category: for example, peanut and egg extracts supply food context, and
Penicillin G supplies medication context. No category is inferred solely
from Drug-domain membership.

With absent `type`, a supported substance maps to a mechanism-neutral
propensity finding: medication (optionally with biologic) uses Propensity
to adverse reactions to drug (`4305025`), food alone uses Propensity to
adverse reactions to food (`4303802`), and other category sets or an
unknown category use Propensity to adverse reaction (`4172024`). The
original type remains absent; no allergy or intolerance mechanism is
inferred. The substance value is resolved independently. Existing
supported findings can supply their own mechanism and negative
statements retain their meaning. Conflicting evidence leaves the
affected concept unmapped.
A single identified substance can still populate the value when only
its category context conflicts. Distinct conflicting substances,
positive/negative mixtures, finding/substance mixtures, and multiple
standard substance targets do not select a substance value by input
order. Equivalent supported translations may share one value;
unresolved translations are disclosed and are not used as substances.
Finding-only, value-only, and neither-resolved partial rows are retained.

`mappings.resolution.allergy` retains supplied type/categories, coded
clinical/verification statuses, the date-source element, per-coding
interpretation, derived categories, and reported information loss. The
finding and substance have separate mappings linked to the same row and
fields. Broader findings retain source specificity in this metadata.
Codes outside contextual policy coverage retain existing domain-based
mapping, with the contextual coverage outcome reported separately.
Text-only inputs retain their text-only behavior. Reaction-substance
fallback and published `Maps to value` relationships are not applied.
Null placeholders in repeating FHIR category primitives carry no category
value and are omitted from category interpretation and audit values.
An invalid supplied type/category drops only the affected AllergyIntolerance
before concept resolution. Other resources are still processed. The
`dropped` entry identifies the resource and reports
`allergy_type_unrecognized` or `allergy_category_unrecognized`.

For example, a Condition coded with ICD10CM `Z79.4` can produce a mapped
`observation` row. `Z86.73` and ICD-O-3 `8140/3` also map to concepts in
the Observation domain. Use `mappings.omop_table` and `mappings.omop_id`
to locate each result; the FHIR resource type alone does not determine
the output table.

Clinical rows include available person/visit/provider links, concept and
source concept IDs, source value, source type provenance, and start
timing. Dates follow the source resource's timing rules below, regardless
of the output table. For example, a Condition follows its
`onset[x]` / `recordedDate` timing rule even when returned as an
`observation`. End dates are populated only in tables with end columns;
for rows not listed in `rows_for_review`, they also contribute to the
request-local observation period when the output table has no end column.

Source-specific fields are populated only for the corresponding source
and destination: Condition status in `condition_occurrence`, medication
dosage/supply and Immunization lot details in `drug_exposure`, and
Observation values/units/ranges in `measurement` or `observation` where
those columns exist. Mapping notes explain the output table and which
fields are populated. Coded medication/immunization routes on rows outside
`drug_exposure`, and Observation values on rows outside `measurement` /
`observation`, are retained in `mappings` linked to the output row, with
`omop_field` omitted and `selected: false`. Coded routes are checked
against the OMOP Route domain; those Observation values are preserved
without concept resolution.

Note destinations are unsupported. If no standard concept
valid for a supported destination is found, the resource produces a row
in its default table with concept ID `0` and `UNMAPPED` status. Its
source concept ID is also `0`, except that allergy rows retain a known
original source identity from their coding evidence. A `DOMAIN_MISMATCH`
outcome is identified in the mapping
note. Text-only clinical inputs can also produce rows in another supported
table when semantic mapping selects a standard concept valid for that destination;
without a validated match, they use their default tables. Domain-routed
clinical records produce one row each even when their code has multiple
vocabulary mapping targets; DeviceUseStatement event granularity is
described below. Vocabulary `Maps to value` mappings are not applied.

`Medication` is reference data for medication resources; it does not
create its own row because OMOP CDM has no Medication table. Administrative
linkages (provider, care site, and location) are best-effort and limited to
references supplied in the request. `Patient.managingOrganization` is a
record custodian, not a care-delivery site. Provider specialties resolve
independently to standard Provider concepts. Recorded `Practitioner.gender`
is distinct from Person
demographics: `male` and `female` resolve to validated OMOP Gender
concepts in `provider.gender_concept_id`; `other`, `unknown`, and absent
gender remain unmapped. `Address.country` is resolved to `location.country_concept_id`,
and CMS Place of Service codings in `Location.type` are resolved to
`care_site.place_of_service_concept_id`.
Within one request, Practitioners with the same single distinct supplied
NPI value merge into one provider row only when all supplied mapped identity
attributes in the entire NPI group agree. The NPI system may be
`http://hl7.org/fhir/sid/us-npi` (preferred in FHIR R4),
`urn:oid:2.16.840.1.113883.4.6`, or bare `2.16.840.1.113883.4.6`;
these forms are equivalent for matching. OID forms are accepted for compatibility.
The same matching rule applies to Practitioners contained in valid role
references. NPI values are compared exactly as supplied, without format
or checksum validation. Blank values and unknown markers `UNK` and
`UNKNOWN` are treated as missing and do not populate `npi` or participate
in matching. Marker detection ignores case and surrounding whitespace;
all other values are preserved without trimming. Other identifier systems and names
do not trigger a merge. Missing attributes can enrich a compatible merged row.
Compatibility compares the name rendered from each Practitioner's first
`name` entry, its gender, its first non-empty DEA identifier, and its parsed
birth year. Differences in birth month/day within one year do not conflict.
Rendered names are compared exactly: `Jane Smith` and `Dr. Jane Smith`
conflict even when they share an NPI.
If any of these attributes conflict, every resource in that NPI group stays
separate, including resources missing the conflicting attribute. Source
attributes and unambiguous structural reference links are preserved; no
conflicting value is selected. Each affected row has `CONFLICTING`
diagnostics at `name`, `gender`, `identifier`, or `birthDate`, linked by
`omop_table: provider` and `omop_id`. All source gender mappings link to
their retained or merged provider row.
Repeated copies of one NPI on a resource are allowed. A resource with
multiple distinct NPIs stays separate, leaves `npi` unset, preserves its
source-resource identity in `provider_source_value`, and reports a
`CONFLICTING` diagnostic at `identifier` linked by
`omop_table: provider` and `omop_id`.
Row IDs are per response. The API does not merge across requests. For a
Practitioner with one NPI, `provider_source_value` is that NPI, even when
its group conflicts. Consumers can use it to deduplicate compatible
providers across requests, but must preserve rows flagged by identity
conflict diagnostics and check compatibility across responses. Without
one unambiguous NPI, source-resource identity is preserved without a
person-level deduplication guarantee.
A `PractitionerRole` that identifies one supplied `Practitioner` aliases
that canonical provider: by a top-level structural reference, a
parent-contained `#id` reference, or an `identifier.system` and
`identifier.value` match against a top-level Practitioner. Identifier
matching uses the equivalent NPI systems and missing-value rules above;
all other systems and all supplied identifiers match exactly. No remote
identifier lookup is performed. When `Reference.type` is present it must
be `Practitioner`; duplicate contained IDs and identifier matches to
different canonical providers are ambiguous. An explicit reference that
is unresolved, ambiguous, or unsupported retains a role-fallback provider
row and is returned in `diagnostics`. `provider_role_contexts` preserves role-specific
specialty and care-site context that a canonical OMOP provider row cannot
represent together.

A role whose practitioner reference has only a blank or unknown NPI
identifier follows the missing-identifier behavior: its fallback row has
an `UNSUPPORTED` diagnostic explaining that a usable identifier or literal
reference is required. An unambiguous literal reference still links to
its Practitioner when the NPI is missing or unknown. Original supplied
unknown markers remain in the role's `practitioner_identifier` metadata.

Each `PractitionerRole.specialty` entry resolves independently using its
supplied codings and explicit text from that entry. NUCC codings resolve
directly; other supported codings may use the UMLS bridge. Text fallback
is permitted when every coding has a nonblank code and a well-formed,
unsupported system identifier. Supported systems, mixed supported and
unsupported systems, and incomplete or malformed codings block fallback.
A supported coding remains authoritative even when the text differs.
Within one specialty entry, complete codings from well-formed unsupported
systems do not block supported codings that independently resolve to the
same standard Provider concept. Unsupported companions remain unsupported
in the coding audit and acquire no crosswalk. Missing or malformed
companions, failures of recognized codings, and disagreements between
supported codings still block selection. For example, NUCC `208000000X` alongside a complete local
`PEDS` coding can resolve to Pediatric Medicine, with or without text
and in either coding order. This uses the supported coding's mapping
and source concept, rather than text fallback.
Coding displays do not supply text fallback evidence.
Unsupported system identifiers must be absolute URIs without embedded
whitespace, user information, or fragments. HTTP(S) identifiers require
a host; URNs require a namespace and a nonempty namespace-specific value.
Bare labels such as `Epic` do not qualify.
Text uses deterministic vocabulary assertions in order: standard Provider
concept name, English OMOP synonym, then an English UMLS string on a
CUI with a NUCC atom, then a NUCC preferred-term label with its grouping
prefix removed. The last layer retains the entire classification and
specialization label, including qualifications. An ambiguous layer stops
resolution. No semantic search or ML matching is used.
Each role's input remains visible in `mappings`, including repeated
identical inputs across one provider's roles.
`specialty_concept_id` is populated only when every distinct supplied
input resolves to the same standard Provider concept. With no inputs,
or an unresolved, ambiguous, or conflicting input, it stays `0`.
A role without a specialty contributes no input. The endpoint applies
no frequency or hierarchy selection. Each input's outcome and matching
route (layer, matched string, and UMLS CUI/SAB when applicable) appear
in `mappings` with `omop_field: specialty_concept_id`. An individually
resolved input can coexist with a provider concept of `0` when another
input fails or disagrees. Specialty mappings have `selected: false`:
the source text remains in `specialty_source_value` when supplied source
values agree, and every original value remains in role contexts and mappings.
Specialty mapping evidence includes `specialty_resolution` with the text
fallback decision and each coding's independent outcome. A successful
text fallback reports `MAPPED` and source concept ID `0`; its local
codings remain unsupported in that audit. For example, complete local
codings with explicit `Pediatrics` text can resolve to Pediatric Medicine
through `NUCC_LABEL`. Adding a different or unresolved specialty still
keeps the provider's singular concept at `0`.
Compound phrasings without a vocabulary assertion remain unresolved.
For example, `Pulmonology` stays unresolved while `Pulmonologist`
resolves to Pulmonary Disease. Results depend on `vocab_version`.

Patient demographics:
- Sex at birth, race, and ethnicity are read from these US Core
  extensions, with their US Core 6.1.0 structures and value sets, on
  any Patient (US Core profile conformance is not required). Sex at
  birth falls back to Patient `gender`. Other extensions, including US
  Core sex and gender identity, are ignored.
  - Birth sex:
    `http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex`
    (`valueCode` from `http://hl7.org/fhir/us/core/ValueSet/birthsex`)
  - Race:
    `http://hl7.org/fhir/us/core/StructureDefinition/us-core-race`
    (`ombCategory` from
    `http://hl7.org/fhir/us/core/ValueSet/omb-race-category`)
  - Ethnicity:
    `http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity`
    (`ombCategory` from
    `http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category`)
- `gender_concept_id` is sex at birth. A supplied birth sex always
  decides it: `M` and `F` are resolved; `UNK`, `ASKU`, `OTH`, a code
  outside the value set, conflicting values, and a birth sex without
  `valueCode` leave it `0`, and Patient `gender` is not used.
- Without a birth sex, Patient `gender` `male` or `female` is resolved
  under the OMOP convention that the supplied gender represents sex at
  birth; `other` and `unknown` keep concept `0`.
- `gender_source_value` is the chosen source code (`F` for birth sex,
  `female` for Patient `gender`).
- Each race category is resolved separately, and null flavors (`UNK`,
  `ASKU`) are ignored. One distinct standard race sets
  `race_concept_id`. More than one sets it to `1546847` (More than one
  race) and adds one `observation` row per race, with
  `observation_concept_id` `4013886` (Race), the race in
  `value_as_concept_id`, `observation_type_concept_id` `32817`, the
  category code in `value_source_value`, and no
  `observation_source_value` or `observation_date`. A loading pipeline
  that requires `observation_date` must apply its own date policy.
- The single non-null ethnicity category is resolved, and null flavors
  are ignored; more than one distinct category leaves
  `ethnicity_concept_id` `0`. Ethnicity is not derived from race, and
  no demographic is inferred from names, addresses, or other
  extensions.
- `race_source_value` and `ethnicity_source_value` list every supplied
  category and detailed code in source order, joined with `|`, or the
  extension text when no code is supplied. Detailed codes and text are
  not resolved.
- Every supplied birth sex, gender, and OMB category code has a
  `mappings` entry whose `note` names its source and outcome. When a
  birth sex is supplied, Patient `gender` is reported unselected with
  the note `FHIR administrative gender; not used, birth sex supplied`.
  Conflicting values and a birth sex without `valueCode` are also
  returned in `diagnostics` with path `extension:birthsex` or
  `extension:ethnicity`. `summary` counts each demographic field once,
  as described under `Summary`.
- Differences from the reference conventions: Vulcan's example gender
  ConceptMap maps `other` and `unknown` to concepts, which stay `0`
  here; more than one race follows the OHDSI THEMIS convention, also
  used by Vulcan, rather than the CDM 5.4 note that mixed races use
  `0`; and Vulcan's suggested `observation` rows for multiple
  ethnicities are not produced.

`Specimen` produces a `specimen` row only with an explicitly resolvable
top-level Patient subject. Missing collection dates or material retain
useful partial rows with linked diagnostics; those rows may require
downstream completion before loading into a strict CDM instance.
References support `Patient/id` and exact Bundle
fullUrl matches (including URNs and absolute URLs); contained, logical,
display-only, missing, non-Patient, and unresolved subjects never use the
sole Patient fallback. Reference.type, when supplied, must identify Patient.
Unsafe patient attribution and ineligible status drop only that Specimen
with `dropped` and `diagnostics`; a missing Patient in the entire request
remains a 400. Missing material is concept ID 0 with a `type` diagnostic
and no terminology mapping/summary count. Supplied unmapped material is
also 0, with its separate vocabulary mapping outcome and retained source code.
Material (`type`) resolves against the Specimen domain, coded UCUM
collection quantity units against Unit, and `collection.bodySite` against
Spec Anatomic Site. Supplied unmapped optional concepts are 0; absent
unit and site IDs are explicit null. Text-only body sites preserve their
source text with site concept ID 0 and an `UNMAPPED` mapping; they do not
produce a text-based concept suggestion. Material descriptions follow
the semantic-mapping policy above. Original source codes and text-only
descriptions are preserved.
Numeric quantity is copied without
unit conversion; invalid or comparator-bearing quantities are omitted
with diagnostics without dropping the row. Missing optional data is allowed.
Collection time uses `collection.collectedDateTime` or
`collection.collectedPeriod.start`; end-only, partial, invalid, and absent
dates leave specimen_date/specimen_datetime omitted with linked diagnostics.
Both collected forms together are conflicting: retain the row without
selecting a date. Period end and receivedTime never substitute for collection
start. `specimen_source_contexts.collection_timing` preserves raw dateTime,
Period boundaries, receivedTime, and the selected source path when a date
is populated, including partial precision and original timezone offsets.
`specimen_collection_date_missing`, `specimen_collection_date_partial`, and
`specimen_collection_date_unusable` distinguish absent, partial, and invalid
source dates; `specimen_collection_multiple_forms` reports conflicting choices.
`specimen_type_concept_id: 32817` is EHR provenance, independent of material
and availability. Status absent/available/unavailable/unsatisfactory is
supported; entered-in-error and unrecognized statuses drop the specimen.
`specimen_source_contexts.status` preserves the supplied availability
status for emitted rows; it is omitted when no status was supplied.
Disease status is not inferred. Source identity precedence is resource id,
then first identifier with a nonempty value in source array order, then
accessionIdentifier.value, then Bundle fullUrl. No identity is fabricated;
`specimen_source_contexts` preserves all valued identifier system/value
pairs, accession identity, resource id/fullUrl, and the selected source path.
Parent/derived specimens emit independently when each has its own Patient;
missing date/material remains partial rather than being inherited. Parent
and Measurement-to-Specimen links are not represented. Consuming CDM
loaders own required-date completion, durable IDs, and dataset completeness.
Source baseline is FHIR R4 4.0.1, with supported common fields reviewed against
US Core Specimen 7.0.0; full profile conformance is not validated here.

**Device use and exposure**

DeviceUseStatement accepts active, completed, stopped, and on-hold use;
intended, entered-in-error, missing, and unrecognized statuses are omitted
with source-specific diagnostics. Its subject must explicitly resolve to
an emitted Patient. Group, contained-Patient, identifier-only, external
fetching, and sole-Patient attribution are unsupported for this path.
Device references support exact Type/id and Bundle fullUrl/URN matches,
plus unambiguous contained Devices scoped to the referring statement.
Missing, wrong-type, unresolved, or ambiguous Device details retain a
known-patient use row with device concept 0 and diagnostics. Missing type
evidence has no vocabulary mapping entry; supplied unmapped type evidence
has a mapping outcome. Inventory-only Device records emit no exposure.

timingDateTime supplies the start only; timingPeriod preserves supplied
boundaries independently. Each timingTiming.event produces a separate
row, including a partial row for an unusable event, with its zero-based
event_index in device_exposure_contexts.exposures. Repeat rules without events
retain one partial row; events plus rules produce only the event rows.
No recurrence, continuous min/max interval, status-derived end date, or
recordedOn fallback is inferred. Year/month precision and malformed
individual dates leave affected columns absent. Competing timing choices
or a provably reversed Period leave both bounds absent. Supplied precision,
offsets, schedules, and omission/conflict reasons remain in source context
and diagnostics. Other clinical paths retain their own timing semantics.

device_exposure_contexts contains one entry per source record that produced
device exposures. Its exposures array links all rows derived from that
record by device_exposure_id and, for Timing events, event_index. Shared
timing, device evidence, and quantity_basis appear once per source record.
Contexts are not combined by resource id or device identity; distinct
records remain separate even when their identifiers match or are absent.

device_source_value uses original type/clinical coding, never inventory
or resource identity. An unambiguous Device.udiCarrier.deviceIdentifier
supplies unique_device_id. Competing identifiers leave it absent and are
preserved with issuer/jurisdiction/carrier context. production_id remains
absent; carriers, lot, serial, manufacture, and expiry evidence remain in
device_exposure_contexts.

DeviceUseStatement rows use device_type_concept_id 32817 (EHR), with
provider_id, visit_occurrence_id, and visit_detail_id unset.
Routed rows retain their source classification, explicit visit links to
emitted same-patient visits, and compatible performer links;
Condition/Procedure recorder/asserter and
MedicationStatement informationSource do not supply device provider_id.
Supplied source, encounter, context, recorder, asserter, performer, and
informationSource values on DeviceUseStatement are retained only in
device_exposure_contexts.

Device exposure quantity is reported as follows:

- When the source has no quantity, dose, rate, or numeric Observation
  result field, quantity is 1 and device_exposure_contexts.quantity_basis
  is default_absent_count.
- When such a field is supplied, including a null or malformed value,
  quantity is omitted and quantity_basis is unsupported_supplied_evidence.
  The original values remain in device_exposure_contexts.evidence, and
  an UNSUPPORTED diagnostic identifies each supplied field.

For example, an Observation with valueQuantity.value of 2 returned as a
device exposure has no quantity; the value 2 remains in its source context.
timingTiming.repeat.count remains in source context and does not set
quantity. unit_concept_id and unit_source_concept_id are always null.

Distinct eligible statements and routed clinical records remain separate,
including overlapping use and equal Timing events. derivedFrom is retained
as supporting context, not duplicate identity. Row counts therefore need
not count distinct uses or physical devices. IDs are request-local exposure
identities. Before loading a CDM dataset, callers must assign durable IDs
and populate any required fields omitted from partial rows.

Unsupported resource types are accepted in a Bundle but ignored: they
create no row and no `dropped` entry. `dropped` is reserved for supported
row-producing resources that cannot safely produce a positive OMOP row:
required subject/patient, clinical code/text, or medication data may be
unusable, or the resource may explicitly negate or fail the documented
clinical-event eligibility policy. A single-Patient Bundle uses the sole
Patient only when `subject`/`patient` is absent, except DeviceUseStatement
and Specimen, which require explicit Patient subjects. An explicit subject/patient
reference that is unresolved, ambiguous, or unsupported drops the clinical
resource in every request scope.

Eligibility distinguishes clinical validity, performed/taken evidence, and
administrative workflow state. Entered-in-error and explicitly
non-performed events never produce a positive clinical-event row, and
unrecognized required statuses are dropped except the retained Condition and
Encounter cases below. Condition accepts absent or confirmed canonical-HL7
`verificationStatus` without a status retention reason; uncertain or unreadable
supplied verification is retained and indexed. Clinical course is not a
diagnosis-role mapping. Procedures accept completed or stopped events.
Medication requests are prescription evidence only: `doNotPerform`, drafts,
cancellations, and non-authorizing intents are dropped. Medication statements
accept active, completed, stopped, or on-hold reported use; administrations
accept completed, in-progress, on-hold, or stopped events. An on-hold
administration also needs an `effectiveDateTime` or `effectivePeriod.start`
that supplies start evidence; a valid partial date remains an undated row.
An on-hold administration is started evidence that is temporarily paused and
expected to continue. MedicationDispense accepts completed records,
including completed partial fills. Stopped records require a valid
`whenHandedOver`, including partial dates, as evidence of actual handover.
Preparation, in-progress (ready for pickup), on-hold, cancelled, declined,
entered-in-error, unknown, missing, and unrecognized statuses are dropped.
A completed dispense with missing or unusable handover timing remains a
partial row; preparation time never substitutes for handover.
Immunizations require completed
status. Observations accept final,
amended, or corrected status; registered,
preliminary, cancelled, entered-in-error, and missing statuses are
dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7
`verificationStatus` as a reported allergy, but drops refuted,
entered-in-error, and unreadable supplied verification statuses. Invalid
supplied allergy type/category also drops that resource, for both coded
and text-only statements. Encounter
accepts arrived, triaged, in-progress, onleave, or finished status, but drops
planned, cancelled, and entered-in-error statuses. Unknown, missing, and unreadable
Encounter statuses are retained and indexed without imputation. An eligible
encounter without `Period.end` remains a partial visit; no end date is invented.
MedicationStatement, Observation, and Procedure with explicit `unknown`
status are also retained and indexed in `rows_for_review` when otherwise
shapeable. Missing or unreadable statuses on these three resource types
remain dropped. Retention preserves source status and does not establish
that an event occurred or medication was taken. Device placement still
requires eligible use evidence; unknown-status records cannot produce
`device_exposure` rows.

The mapped OMOP concept's domain determines the clinical output table.
For Observations, numeric and nonnumeric `value[x]` forms determine the
preferred table only when the code is valid for both `measurement` and
`observation`. Unresolved Observations retain `measurement` rows for
numeric values and `observation` rows for other values. In these two
tables, numeric values populate `value_as_number`; other non-coded values
populate `value_as_string` for an `observation` or `value_source_value`
for a `measurement`. Coded `valueCodeableConcept` values are resolved
against `value_as_concept_id` in these tables and use the selected
bare code in `value_source_value`, leaving an `observation`'s
`value_as_string` empty; unmapped or target-invalid coded values remain
`0`. Active standard concepts from any OMOP domain are valid for
`value_as_concept_id` per CDM 5.4. For example, a blood-culture Measurement
can record *Staphylococcus aureus* as its coded result, even though the
organism concept belongs to OMOP's Observation domain.
For other clinical output tables, Observation values are retained only
in `mappings`, without concept resolution or an `omop_field`, and with
`selected: false`.
Other unsupported `value[x]` forms and Observation components do not
populate separate converted values. A
numeric comparator (`<`, `<=`, `>`, `>=`) is represented only by a
measurement's `operator_concept_id`.

For Observations returned as `measurement` or `observation` rows,
Quantity units resolve independently against the table's
`unit_concept_id`.
Only coded UCUM (`http://unitsofmeasure.org` or its
OID `2.16.840.1.113883.6.8`, bare or `urn:oid:`) is supported. Codes are
case-sensitive: no spelling aliases, text-only guesses, or numeric
conversion are applied. Coded UCUM units map to valid standard OMOP
Unit concepts using the release selected by `vocab_version`.
Mappings are direct or follow an active OMOP `Maps to` relationship;
UCUM units do not use a UMLS bridge.
Unknown codes,
vocabulary gaps, text-only units, missing coding, and unsupported
systems keep the row and use `0`; absent units use JSON `null` (the
field is present). Explicit dimensionless code `1` is a supplied unit
and resolves or remains `0`; it is never treated as absent.
`unit_source_value` contains Quantity.code when supplied, otherwise
Quantity.unit. A separate unit `mappings` entry preserves the original
Quantity.system/code in `source_system`/`source_code` and the exact
human-readable Quantity.unit in `source_name`, with its own outcome.
Quantity.unit provides display text and does not affect unit matching.
Measurement also returns nullable `unit_source_concept_id`, identifying
the OMOP source concept for Quantity.system/code when available,
otherwise `0` for a supplied unit.
Observation has no such column. Resolving a unit does not change
numeric values, comparators, or reference ranges.
Supported coded UCUM units include `resolution` in their mappings,
whether the unit resolves or remains unmapped:
its outcome and reason code distinguish vocabulary gaps, target-domain
mismatches, and ambiguity. Unresolved or ambiguous units retain the row
with concept ID `0`. Resolved mappings retain the selected concept's
direct or crosswalk provenance. Text-only units, units with missing
coding, and unsupported unit systems omit `resolution`; their `note`
explains the unmapped outcome.

For Observations returned in other clinical tables, units are not resolved
or included as separate mapping outcomes. Device exposure unit IDs remain
null, with supplied quantity and unit evidence retained in
`device_exposure_contexts`.

Compatibility: absent `unit_concept_id` values previously returned `0`
and now return `null`. Coded units use their code in `unit_source_value`
rather than their human-readable text; the text remains in `mappings`.
The Measurement `unit_source_concept_id` field is new.

A standard OMOP `concept_id` is selected for each eligible primary clinical coding
after considering all of the resource's supplied codings. An unambiguous
coded medication or immunization route is checked independently against
the OMOP Route domain. For `drug_exposure` rows, `route_concept_id`
contains the resolved concept ID, or `0` if unmapped; for other output
tables the route is reported only in
`mappings`, without `omop_field` and with `selected: false`.
Alongside the OMOP rows grouped by
table (`tables`), the response carries `mappings` (an entry for every
supported source coding from a resource that shaped a row, linked back to
that row; some, such
as demographic null flavors, are reported without being resolved),
`rows_for_review` (an index of uncertain-status or primary-concept-0 clinical
rows in tables, with original statuses, reasons, and source/row identity),
`provider_role_contexts` (source role details linked to provider rows),
`dropped` (resources that could not be shaped into a row),
`diagnostics` (explicit references that could not safely create a link,
conflicting Practitioner identity attributes, conflicting or unsupported
Patient demographic extensions, and conflicting Encounter classifications),
`vocab_version` (the OMOP vocabulary release codes were resolved
against), and a small `summary` of the resolution outcomes.

A `concept_id` of `0` is reported, not omitted (OMOP "no matching
concept" semantics): it covers a supplied concept without a validated
standard match (`UNMAPPED`).
Supported `Encounter.class` or `Encounter.type` values
may populate `visit_concept_id`. Person demographics and Provider
recorded gender follow the policies above.
Coded Observation values and supported allergy substances may populate
`value_as_concept_id`.
Measurement `operator_concept_id` represents a value comparator (`<`,
`<=`, `>`, `>=`); multiple-race concepts follow the conventions described
above. Clinical `*_source_value` fields contain the selected FHIR code
(or source text for text-only resources).
The corresponding selected `mappings` entry preserves the coding system
and full source-coding provenance.
Known OID-form coding systems are accepted as either FHIR OID URNs (for
example, `urn:oid:2.16.840.1.113883.6.1` for LOINC) or bare OIDs, and
produce the same mappings as their canonical system URLs. Coding
mappings report that canonical URL in `source_system`; Quantity unit
mappings preserve the original Quantity.system, including OID spelling.
An unknown OID remains unchanged in `source_system` and may be
`UNMAPPED`.
Other `*_source_value` fields preserve row-specific raw source values,
such as resource identifiers, names, units, or status codes.
`MedicationRequest` uses `32838` (EHR prescription) and
`MedicationDispense` uses `32825` (EHR dispensing record) for
`drug_type_concept_id`; other current resources use `32817` (EHR). This
is a coarse provenance policy: it does not infer patient-reported,
medication-history, or other more-specific type concepts from FHIR
status fields.

Dates and datetimes:
- A `*_date` is the calendar date (`YYYY-MM-DD`) of a source value with
  at least day precision. A `*_datetime` is set only when that value
  has a time of day, as local time without a UTC offset
  (`YYYY-MM-DDTHH:MM:SS`, with fractional seconds to microseconds when
  supplied): `2024-01-15T23:30:00-05:00` becomes `2024-01-15T23:30:00`.
  A datetime without a timezone is read as local time.
- A partial date (`2024` or `2024-03`) leaves both columns unset.
  It still counts as that source's value, so later sources in the list
  below are not used.
- Free-text timing (such as `onsetString`), `Age` and `Range` forms, and
  values that are not dates are ignored, so a later source in the list
  is used if there is one.
- Other than the sources below and the same-day ends of single-event
  medication records, no date is imputed: partial dates are not
  completed, and a row is not dated from another resource such as its
  Encounter.
- Valid date values never cause a request to be rejected, and the response
  reports missing, partial, malformed, or conflicting timing for Specimen,
  DeviceUseStatement, and MedicationDispense in `diagnostics` while retaining
  partial rows for downstream load completion. Other resources do not report which
  date elements were unusable. An on-hold
  MedicationAdministration is an eligibility exception: it needs a supplied
  effective start as evidence that administration began.
  A stopped MedicationDispense similarly requires supplied handover evidence.

Timing sources, in priority order where several are listed. These rules
apply regardless of the clinical output table; end dates are populated
only where the table has an end column, and `verbatim_end_date` is set
only for medication resources returned as `drug_exposure` rows:
- `Patient`: `birthDate` sets `year_of_birth`, `month_of_birth`, and
  `day_of_birth` from the parts it supplies; `birth_datetime` is not
  set. `deceasedDateTime` sets the `death` dates.
- `Practitioner`: `birthDate` sets the provider's `year_of_birth`.
- `Encounter`: `period.start` and `period.end`.
- `Condition`: start from `onsetDateTime` or `onsetPeriod.start`, then
  `recordedDate` (when the condition was recorded, not when it began);
  end from `abatementDateTime` or `abatementPeriod.end`.
- `Procedure`: start from `performedDateTime` or
  `performedPeriod.start`; end from `performedPeriod.end` only.
- `DeviceUseStatement`: `timingDateTime` sets the start only;
  `timingPeriod.start` and `timingPeriod.end` supply independent bounds;
  each `timingTiming.event` produces one start-only row. A schedule
  without explicit events produces one row without dates.
- `Specimen`: `collection.collectedDateTime` or `collection.collectedPeriod.start`;
  missing day precision retains an undated specimen with diagnostics.
- `Observation`: `effectiveDateTime`, `effectivePeriod.start`, or
  `effectiveInstant`.
- `AllergyIntolerance`: `recordedDate`, then `onsetDateTime` or
  `onsetPeriod.start`.
- `MedicationStatement`: start from `effectiveDateTime` or
  `effectivePeriod.start`; end and `verbatim_end_date` from
  `effectivePeriod.end`. `dateAsserted` records when the statement was
  made and is not used.
- `MedicationAdministration`: an `effectiveDateTime` is a single event
  that sets both start and end; an `effectivePeriod` sets the start
  and, when present, the end and `verbatim_end_date`.
- `Immunization`: `occurrenceDateTime` is a single event that sets both
  start and end; `expirationDate` is not used.
- `MedicationRequest`: `authoredOn`, the order date, sets the start; it
  is not evidence of administration. No end is set, and the validity
  period is not used as an exposure duration.
- `MedicationDispense`: `whenHandedOver` sets the start. Missing, partial,
  or invalid handover leaves the start unset with a diagnostic. Comparable
  handover/preparation values proving handover before preparation also
  leave the start unset with a `CONFLICTING` diagnostic. `whenPrepared`,
  authorizing orders, and related administrations never supply timing.
  No exposure end or `verbatim_end_date` is inferred, including from
  `daysSupply`. Raw handover/preparation values retain precision and offsets
  in `medication_dispense_source_contexts.source`.
- Differences from the Vulcan maps: `birth_datetime` is not set from
  `birthDate`, Condition also reads `onsetPeriod.start`, and
  AllergyIntolerance falls back to its onset when `recordedDate` is
  missing.

Medication details for resources returned as `drug_exposure` rows:
- For `MedicationRequest`, `dispenseRequest.numberOfRepeatsAllowed` sets
  `refills` and a whole-day `expectedSupplyDuration` sets `days_supply`.
- For `MedicationDispense`, `daysSupply` sets `days_supply` only for a
  positive whole number of coded UCUM `d` days without a supplied comparator.
  The canonical UCUM URL, bare OID, and OID URN are accepted. Other units,
  fractions, text-only units, and malformed values leave it absent with a
  diagnostic; absent daysSupply is allowed. Refills are not inherited.
- All non-empty dosage text is preserved in `sig`.
- Coded dosage routes and `Immunization.route` are target-validated in
  the OMOP Route domain. Conflicting routes are left unset; route
  codings shared by every dosage instruction identify the same route.
- `Immunization.lotNumber` is preserved in `lot_number`.

MedicationDispense requires an explicit subject resolving to a Patient
supplied in the request; Groups and missing subjects are unsupported.
Source fields are based on FHIR R4 4.0.1 and reviewed against
[US Core MedicationDispense 7.0.0](https://hl7.org/fhir/us/core/STU7/StructureDefinition-us-core-medicationdispense.html).
Full profile conformance is not validated. Although US Core requires
handover on completed records, this API retains such incomplete records
with missing-handover diagnostics as partial conversion output.
Supply either a usable `medicationCodeableConcept` (coded or text-only),
or a `medicationReference` resolving to a Medication with usable code/text.
Both choice forms together are conflicting and drop the dispense.
Exact relative, Bundle fullUrl, and unambiguous contained Medication
references are supported. Unresolved references are not rescued by display
text; missing or ambiguous medication identity drops the dispense with a
diagnostic. A usable but unmapped drug retains concept ID 0 and its
mapping outcome in a row indexed for review.
`context` links only to a supplied Encounter for the same patient.
The first resolvable Practitioner/PractitionerRole in `performer.actor`
supplies `provider_id`; other actor types do not supply a provider.
Failed explicit links have diagnostics. Authorizing prescriptions are
checked for request-local MedicationRequest identity and patient agreement;
failures do not discard the dispense. They never supply medication,
instructions, refills, timing, or prescription provenance to a dispense.
Dispense instructions alone supply `sig` and route; conflicting routes
remain unset with a diagnostic and original instructions in source context.
Orders, dispenses, and administrations emit independently, with separate
source identity and no deduplication merely because they concern the same drug.
Every emitted dispensing drug row has a `whenHandedOver/daysSupply`
diagnostic beginning `medication_dispense_end_date_absent` because the
CDM-required exposure end remains absent. Missing/partial/unusable handover
diagnostics begin `medication_dispense_handover_missing`,
`medication_dispense_handover_partial`, or `medication_dispense_handover_unusable`.

Encounter details:
- Encounter classifications must supply both `Coding.system` and
  `Coding.code` to map to a standard OMOP Visit concept. For HL7
  encounter class codes with system
  `http://terminology.hl7.org/CodeSystem/v3-ActCode` or
  `http://hl7.org/fhir/v3/ActCode`, the supported mappings are:
  - `IMP` (inpatient encounter) -> 9201 (Inpatient Visit)
  - `AMB` (ambulatory encounter) -> 9202 (Outpatient Visit)
  - `EMER` (emergency encounter) -> 9203 (Emergency Room Visit)
  - `VR` (virtual encounter) -> 722455 (Telehealth)
  - `HH` (home health encounter) -> 581476 (Home Visit)

  `OBSENC` (observation encounter) has no direct class mapping. Other
  class or type codes can be used when they have a valid standard OMOP
  Visit mapping in the selected vocabulary release. Unsupported
  classifications retain `visit_concept_id` of `0` unless a supported
  type supplies the Visit as described below; they never default to
  outpatient.
- A mapped `Encounter.class` determines `visit_concept_id`. A mapped
  type that disagrees with it produces a `CONFLICTING` diagnostic with
  path `class/type`, while the class mapping remains selected.
  If class is missing or unmapped, type supplies the Visit only when
  all mapped type classifications agree on the same standard Visit
  concept. Codings within one type CodeableConcept are alternative
  encodings of that classification. When separate type classifications
  map to different Visit concepts, no type is selected,
  `visit_concept_id` remains `0`, and a `CONFLICTING` diagnostic has
  path `type`.
- `visit_source_value` contains the selected class or type code;
  `mappings` preserves its coding system and identifies which
  classification was selected. `visit_source_concept_id` identifies
  the selected original source coding's OMOP concept when available,
  and is `0` otherwise, including for the HL7 encounter class codes
  listed above. Each eligible Encounter produces one Visit;
  `classHistory`, `partOf`, and admission/discharge concepts are not
  mapped.

- Direct `MedicationRequest.dispenseRequest.quantity`, `MedicationDispense.quantity`,
  `MedicationAdministration.dosage.dose`, and `Immunization.doseQuantity`
  can set `quantity` under the formulation policies below. Quantities
  must be positive finite numbers with a supported `system`/`code` pair
  and no supplied `comparator`. Ingredient amounts and injection volumes
  use `http://unitsofmeasure.org` (or its bare OID or
  `urn:oid:2.16.840.1.113883.6.8`) with case-sensitive codes matching or
  convertible to vocabulary-backed strength units. Exact unit matches,
  including `[U]` for insulin and heparin strengths, are accepted without
  a unit conversion.
  When codes differ, both source and strength units must belong to the
  same supported group: mass (`ug`, `mg`, `g`), volume (`uL`, `mL`, `L`),
  or milliequivalent representations (`meq`, `10*-3.eq`). Other conversions,
  including `kg`, `ML`, `Mg`, `[drp]`, `mol`, `mmol`, `%`, `1`, and generic
  annotations such as `{vial}` or `{syringe}`, leave `quantity` unset with
  `unit_mismatch`. Codes are not case-corrected or inferred from display text.
  The original source system is preserved in the quantity audit.
  Fixed-form counts also accept the explicit codings below. Free-text,
  local, invalid, and cross-dimensional units are not interpreted.

Drug quantity policies follow [CDM v5.4 DRUG_EXPOSURE conventions](https://ohdsi.github.io/CommonDataModel/cdm54.html#drug_exposure).
The selected drug must be a `Clinical Drug` or `Branded Drug`, with one
active dose form and valid vocabulary evidence for the chosen policy.
Strength-based conversions also require one ingredient strength. Supported RxNorm dose forms:
- `fixed_dose_form_count`: Oral Tablet (`317541`), Oral Capsule
  (`316965`), Extended Release Oral Tablet (`316945`), Extended
  Release Oral Capsule (`316943`), Delayed Release Oral Tablet (`10312`),
  or Delayed Release Oral Capsule (`316995`). A source ingredient amount is divided
  by the single positive per-unit ingredient amount after conversion to that
  strength unit when necessary.
  Concentration-based strengths cannot derive counts from ingredient amounts. The
  result is a count of the selected dose form, limited to whole units or
  multiples of one-half or one-third. Derived counts within a relative
  tolerance of 1e-12 of an allowed fraction are normalized to that count
  to remove arithmetic roundoff; other fractions remain unsupported.
  For example, 1,000 mg for a drug
  with 500 mg per tablet produces `quantity: 2` tablets (`DERIVED`). A source
  of 1 g is converted to 1,000 mg and produces the same count.
  Explicit counts are copied (`DIRECT`) when their coding matches the
  selected tablet or capsule form, including the corresponding extended-
  and delayed-release forms: `TAB` / `CAP` under
  `http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm`, or
  `{tbl}` / `{Capsule}` under `http://unitsofmeasure.org`. These exact
  case-sensitive count codings identify the supplied form; they are not
  dimensionally converted as UCUM units. Direct counts do not require
  ingredient strength: combination products and missing/invalid strengths
  do not change the supplied count. Ingredient-strength gaps, including
  missing ingredient or strength-unit references, do not prevent copying
  an explicit count. Drug or dose-form evidence gaps, unclassified or
  ambiguous forms, and gaps whose relevance cannot be established still
  prevent conversion. The whole/half/third rules still apply.
  For example, 20 `TAB` for amoxicillin/clavulanate is 20 tablets, and 30 `TAB` for
  a supported tablet produces `quantity: 30`; `CAP` for that tablet is
  omitted with `unit_mismatch`. Generic counts (`1`, `{Each}`), other
  annotations, packs, and free-text counts are not interpreted.
  See the [FHIR R4 count example](https://hl7.org/fhir/R4/medicationrequest0301.html).
- `clinical_injection_ingredient_amount`: Injectable Solution (`316949`),
  Injectable Suspension (`316950`), or Injection (`1649574`). A source
  ingredient amount is converted to the vocabulary ingredient unit when
  necessary; an exact-unit amount is copied directly. Otherwise, a source
  amount convertible to the concentration's denominator unit is converted
  and multiplied by numerator value / the effective denominator reported in
  the audit evidence. Volume conversion requires a positive finite numerator,
  dimensionally distinct validated UCUM units, a null raw denominator value, and
  `evidence.strength.denominator_basis` with `kind: PER_UNIT` and
  `value: 1`. A null denominator alone is not interpreted as 1. Missing, unknown,
  non-applicable, quantified, or conflicting denominator evidence does
  not support volume conversion. For example, 80 mL with 2 mg/mL
  strength and a `PER_UNIT` basis produces `quantity: 160` mg. A supplied
  160 mg amount for the same drug produces `quantity: 160` directly. A source
  of 0.08 L converts to 80 mL before producing the same 160 mg result.
  This output is already
  the ingredient amount: do not apply the drug-dose guide's
  `dose = quantity × numerator` formula to these injection rows, which
  would multiply by the concentration a second time. Use
  `quantity_transformations.result_unit` to identify the output unit.

Quantified products, packs, prefilled syringes, other liquids and dose
forms, strength-based conversions of combination products, conflicting or incomplete required evidence, and
unsupported source quantities leave `quantity` unset. Other supported
fields and the clinical row are still returned. For example, a quantity
supplied only as `value: 2, unit: tablet` is omitted with
`unsupported_unit`, because a free-text unit cannot establish this policy.
Rate-only administrations and MedicationStatement dosages do not establish
a supported total quantity and are not used for quantity conversion.

`quantity_transformations` audits each supplied quantity at one of the
three direct paths above on a resource returned as a `drug_exposure` row,
including an explicit null or malformed quantity. Each entry preserves
the source, identifies the destination row, and reports `DIRECT`, `DERIVED`, or
`OMITTED`. Successful entries identify their policy, evidence, result,
and result unit; omitted entries give a stable reason. When a source code
differs from the strength unit, `unit_conversion` records the intermediate
converted amount and target unit. Converted results are `DERIVED`, even
when no further concentration arithmetic is needed. A successful conversion
can also be reported when a later policy check omits the final quantity.
Dose-form and unit
concept IDs refer to the response's `vocab_version`. Missing quantities
produce no entry. Resources returned in other clinical tables have no
quantity entry. Unsupported rates and statement dosages produce no entry,
and resources in `dropped` have no quantity entry or destination row.

Medication codes are resolved whether they appear inline
(`medicationCodeableConcept`) or via a `medicationReference` to a contained,
relative (`Type/id`), or bundle-entry (`urn:uuid`) `Medication` resource.
A reference that resolves to another resource type is dropped even when it
supplies display text; an unresolved or display-only reference may use
its display as text-only medication input.
Resources that cannot be shaped into a row — a medication with no usable
code, resolvable reference, or display; any clinical resource whose
subject/patient reference cannot be tied to a person; or an event excluded
by eligibility — are reported under `dropped` rather than emitted as blank
rows. The Bundle must contain at least one Patient resource.

References to top-level resources supplied in the request resolve by
`Type/id` or an exactly matching Bundle `fullUrl` (including `urn:uuid`).
Parent-scoped contained references are supported for medication code lookup,
`DeviceUseStatement.device` details, and `PractitionerRole.practitioner`
enrichment; the latter also supports
request-local identifier matching with the NPI rules above, without a remote lookup. Every
nonzero structural foreign key targets a row in the same response. Missing
optional links remain unset without a diagnostic; an explicit optional
reference that is unresolved, ambiguous, conflicting with the row's
person, or unsupported remains unset and is returned in `diagnostics`
with its source path and outcome.

All row IDs start at `1` for each request and are not stable or global.
For clinical conversion rows whose resource supplies an `id`, `mappings`
associates each row with that source FHIR resource ID. A `person` row
retains the Patient ID or its first identifier value in
`person_source_value`, when present; other reference and derived rows do
not uniformly carry a FHIR resource ID. Input resources without those
source identifiers cannot be correlated across responses from the
returned rows alone. Consumers combining responses need to establish
their own stable keys and remap every primary and foreign key together.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir2omop.create(
    fhir_resources={
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [{"resource": {"resourceType": "Patient", "id": "patient-1", "gender": "female", "birthDate": "1985-07-22"}}, {"resource": {"resourceType": "Condition", "id": "condition-1", "subject": {"reference": "Patient/patient-1"}, "code": {"coding": [{"system": "http://snomed.info/sct", "code": "44054006", "display": "Type 2 diabetes mellitus"}]}, "onsetDateTime": "2024-01-15"}}, {"resource": {"resourceType": "MedicationRequest", "id": "medreq-1", "status": "active", "intent": "order", "subject": {"reference": "Patient/patient-1"}, "medicationReference": {"reference": "#med0"}, "authoredOn": "2024-01-16", "contained": [{"resourceType": "Medication", "id": "med0", "code": {"coding": [{"system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "860975", "display": "metformin hydrochloride 500 MG"}]}}]}}]
    },
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_resources:** `typing.Dict[str, typing.Any]` 

FHIR resources (single resource or Bundle). Must contain at least one
Patient resource. Supported row-producing resources are Patient,
Location, Organization, HealthcareService, Practitioner,
PractitionerRole, Encounter, Specimen, DeviceUseStatement, Condition, Procedure,
MedicationRequest, MedicationStatement, MedicationAdministration, MedicationDispense,
Immunization, Observation, and AllergyIntolerance. Medication and Device
resources provide referenced details without independently producing rows.
Unsupported resource types are accepted in a Bundle but ignored.
    
</dd>
</dl>

<dl>
<dd>

**vocab_version:** `typing.Optional[str]` 

OMOP vocabulary release to use for coded concept resolution. If
omitted or empty, the API uses its default release (`v20260829`).
Specify a release explicitly when reproducibility matters. The response's
`vocab_version`, when present, identifies the release used.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## FhirProvider
<details><summary><code>client.fhir_provider.<a href="src/phenoml/fhir_provider/client.py">create</a>(...) -> FhirProviderResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new FHIR provider configuration with authentication credentials.

Note: The "sandbox" provider type cannot be created via this API - it is managed internally.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir_provider import FhirProviderCreateRequestAuth_ClientSecret

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.create(
    name="Epic Sandbox",
    description="Epic sandbox environment for testing",
    provider="epic",
    base_url="https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
    auth=FhirProviderCreateRequestAuth_ClientSecret(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Display name for the FHIR provider
    
</dd>
</dl>

<dl>
<dd>

**provider:** `Provider` 
    
</dd>
</dl>

<dl>
<dd>

**base_url:** `str` — Base URL of the FHIR server
    
</dd>
</dl>

<dl>
<dd>

**auth:** `FhirProviderCreateRequestAuth` 
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Optional description of the FHIR provider
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir_provider.<a href="src/phenoml/fhir_provider/client.py">list</a>() -> FhirProviderListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a list of all active FHIR providers for the authenticated user.

On shared instances, only sandbox providers are returned.
Sandbox providers return FhirProviderSandboxInfo.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir_provider.<a href="src/phenoml/fhir_provider/client.py">get</a>(...) -> FhirProviderResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a specific FHIR provider configuration by its ID.

Sandbox providers return FhirProviderSandboxInfo.
On shared instances, only sandbox providers can be accessed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.get(
    fhir_provider_id="fhir_provider_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` — ID of the FHIR provider to retrieve
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir_provider.<a href="src/phenoml/fhir_provider/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a FHIR provider.

Note: Sandbox providers cannot be deleted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.delete(
    fhir_provider_id="fhir_provider_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` — ID of the FHIR provider to delete
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Auth Config
<details><summary><code>client.fhir_provider.auth_config.<a href="src/phenoml/fhir_provider/auth_config/client.py">add</a>(...) -> FhirProviderResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Adds a new authentication configuration to an existing FHIR provider.
This enables key rotation and multiple auth configurations per provider.

Note: Sandbox providers cannot be modified.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.fhir_provider import FhirProviderAddAuthConfigRequest_ClientSecret

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.add(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    request=FhirProviderAddAuthConfigRequest_ClientSecret(
        client_id="your-client-id",
        client_secret="your-client-secret",
    ),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` — ID of the FHIR provider to add auth config to
    
</dd>
</dl>

<dl>
<dd>

**request:** `FhirProviderAddAuthConfigRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir_provider.auth_config.<a href="src/phenoml/fhir_provider/auth_config/client.py">set_active</a>(...) -> FhirProviderResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Sets which authentication configuration should be active for a FHIR provider.
Only one auth config can be active at a time.

If the specified auth config is already active, the request succeeds without
making any changes and returns a message indicating the config is already active.

Note: Sandbox providers cannot be modified.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.set_active(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    auth_config_id="auth-config-456",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` — ID of the FHIR provider
    
</dd>
</dl>

<dl>
<dd>

**auth_config_id:** `str` — ID of the auth configuration to set as active
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.fhir_provider.auth_config.<a href="src/phenoml/fhir_provider/auth_config/client.py">remove</a>(...) -> RemoveResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Removes an authentication configuration from a FHIR provider.
Cannot remove the currently active auth configuration.

Note: Sandbox providers cannot be modified.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.fhir_provider.auth_config.remove(
    fhir_provider_id="1716d214-de93-43a4-aa6b-a878d864e2ad",
    auth_config_id="auth-config-456",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_provider_id:** `str` — ID of the FHIR provider
    
</dd>
</dl>

<dl>
<dd>

**auth_config_id:** `str` — ID of the auth configuration to remove
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Implementation Guides
<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">list</a>() -> ImplementationGuideListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns every implementation guide on this instance — both guides that
have stored metadata (a profile_context) and guides referenced by at
least one custom profile — with the number of profiles in each.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">get</a>(...) -> ImplementationGuideDetail</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single implementation guide, including its profile_context and
the ids of the profiles that belong to it.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.get(
    name="acme-cardiology",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — The implementation guide name.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">update</a>(...) -> ImplementationGuideSummary</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Sets (or clears, with an empty value) the natural-language profile_context
for an implementation guide. The context is injected into the LLM during
resource detection to help select the right profiles from this guide.
It applies to every profile in the guide.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.update(
    name="acme-cardiology",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — The implementation guide name.
    
</dd>
</dl>

<dl>
<dd>

**profile_context:** `typing.Optional[str]` — Natural-language context that helps the LLM select the right profiles from this implementation guide during resource detection. An empty value clears the context. Max 2000 characters.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">delete</a>(...)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes the guide's metadata and all its canonical package versions.
Custom profiles and their implementation-guide assignments are preserved.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.delete(
    name="acme-cardiology",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — The implementation guide name.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">create_version</a>(...) -> ImplementationGuideVersionDetail</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Publishes an exact package beneath this guide family. Each guide family
supports one exact package version. Publishing another version returns
`409 Conflict`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.implementation_guides import FhirImplementationGuide

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.create_version(
    name="name",
    implementation_guide=FhirImplementationGuide(
        resource_type="ImplementationGuide",
        url="url",
        version="version",
    ),
    profile_refs=[
        "profile_refs"
    ],
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**implementation_guide:** `FhirImplementationGuide` 
    
</dd>
</dl>

<dl>
<dd>

**profile_refs:** `typing.List[str]` — Exact canonical `url|version` references to builtin or custom profiles. A package can contain at most 250 references.
    
</dd>
</dl>

<dl>
<dd>

**profile_context:** `typing.Optional[str]` — Natural-language profile-selection context for this package.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.implementation_guides.implementation_guides.<a href="src/phenoml/implementation_guides/implementation_guides/client.py">get_version</a>(...) -> ImplementationGuideVersionDetail</code></summary>
<dl>
<dd>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.implementation_guides.implementation_guides.get_version(
    name="name",
    version="1.0.0",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**version:** `str` — The authored ImplementationGuide.version. It may contain letters, numbers, and the punctuation characters `.`, `_`, `~`, `+`, and `-`; it cannot be exactly `.` or `..`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Lang2Fhir
<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">create</a>(...) -> FhirResource</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language text into a structured FHIR resource.

The complete JSON request body is limited to 32 MiB (33,554,432 bytes). The application enforces this whole-envelope limit.

**Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.create(
    version="R4",
    resource="condition-encounter-diagnosis",
    text="Patient has severe persistent asthma with acute exacerbation",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version:** `str` — FHIR version to use
    
</dd>
</dl>

<dl>
<dd>

**resource:** `CreateRequestResource` — Type of FHIR resource to create. Use 'auto' for automatic resource type detection, or specify a supported profile. The default profile set includes US Core profiles and selected base R4 resources. The built-in PhenoML HPO profiles must be requested by id: `phenoml-hpo-condition` and `phenoml-hpo-phenotypic-observation` code findings with the Human Phenotype Ontology, and `phenoml-hpo-head-circumference-tape-measure` and `phenoml-hpo-head-circumference-percentile` record a head circumference measured as a length or stated as an age-adjusted percentile. You can also use any custom profile you've uploaded (if you're a develop or launch customer).
    
</dd>
</dl>

<dl>
<dd>

**text:** `str` — Natural language text to convert
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">create_multi</a>(...) -> CreateMultiResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Analyzes natural language text and extracts multiple FHIR resources, returning them as a transaction Bundle.
Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
Resources are linked with proper references (e.g., Conditions reference the Patient).

The complete JSON request body is limited to 32 MiB (33,554,432 bytes). The application enforces this whole-envelope limit.

**Patient handling.** Every bundle contains exactly one Patient, and every clinical resource references it. When the text names its patient, the Patient is built from the text. When it names several patients, the Patient is the one `primary_patient` names, otherwise the one most of the text is about; the others are not represented as Patients. Otherwise it is built from `primary_patient` when supplied, or is an unidentified Patient carrying only a synthetic identifier. When the text names its patient, the `primary_patient` identifier is added to that Patient unless its name, birth date, or gender contradicts the text's; the response `message` says whether it was added or did not match.

**Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). Every Patient carries a synthetic identifier with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value`, so the bundle remains FHIR-valid and US Core conformant. A medical record number stated in the text is added with `system: "urn:phenoml:lang2fhir-document-mrn"`, and the `primary_patient` identifier is added as described above. Callers who need a tenant-specific namespace should rewrite these systems after extraction.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.create_multi(
    text="John Smith, 45-year-old male, diagnosed with Type 2 Diabetes. Prescribed Metformin 500mg twice daily. Blood pressure 140/90.",
    version="R4",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text containing multiple clinical concepts to extract
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — FHIR version to use
    
</dd>
</dl>

<dl>
<dd>

**provider:** `typing.Optional[str]` — Optional FHIR provider name for provider-specific profiles
    
</dd>
</dl>

<dl>
<dd>

**primary_patient:** `typing.Optional[PrimaryPatient]` — Context for the patient the text is primarily about. When the text does not name its patient, the bundle's Patient is built from these fields. When it does, the identifier is added to that Patient unless its name, birth date, or gender contradicts these fields.
    
</dd>
</dl>

<dl>
<dd>

**patient_reference:** `typing.Optional[PatientReference]` — Deprecated compatibility alias for primary_patient.identifier. Cannot be combined with primary_patient.
    
</dd>
</dl>

<dl>
<dd>

**implementation_guide:** `typing.Optional[str]` — Implementation Guide to generate resources under. `us_core` (the default) and `phenoml_hpo` select a built-in guide. Any other value is a custom Implementation Guide name: its profiles are included alongside the US Core profiles, which are always the base layer. A custom name that matches no uploaded Implementation Guide returns 404.
    
</dd>
</dl>

<dl>
<dd>

**detection_effort:** `typing.Optional[CreateMultiRequestDetectionEffort]` — Deprecated and ignored: both values produce the same result. This field will be removed in a future release.
    
</dd>
</dl>

<dl>
<dd>

**validation_method:** `typing.Optional[CreateMultiRequestValidationMethod]` — FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips.
    
</dd>
</dl>

<dl>
<dd>

**resource_review:** `typing.Optional[ResourceReview]` 
    
</dd>
</dl>

<dl>
<dd>

**small_note:** `typing.Optional[bool]` — Bills the request at the lower small-note rate. When true, `text` must be at most 15,360 bytes (15 KiB) when UTF-8 encoded; longer text is rejected with a 400 error. Extraction behavior is the same as a standard request.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">search</a>(...) -> SearchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language text into FHIR search parameters.
Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.

Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition,
Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location,
Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner,
PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson,
Schedule, ServiceRequest, Slot, and Specimen.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.search(
    text="Appointments between March 2-9, 2025",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` 

Natural language text to convert into FHIR search parameters.
The system will automatically identify the appropriate resource type and generate valid search parameters.

Examples:
- "Appointments between March 2-9, 2025" → Appointment search with date range
- "Patients with diabetes" → Condition search with code parameter
- "Active medication requests for metformin" → MedicationRequest search
- "Lab results for creatinine" → DiagnosticReport search
- "Dr. Smith's schedule" → Practitioner or Schedule search
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">upload_profile</a>(...) -> UploadProfileResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

**Deprecated — use `POST /fhir/profiles` instead.** This route continues to work
and operates on the same custom profiles, so no migration is required; it
will be removed in a future release. Note that `POST /fhir/profiles` does not
accept `profile_context`; set implementation-guide context with
`PUT /fhir/implementation-guides/{name}`.

Upload a custom FHIR StructureDefinition profile for use with the lang2fhir service.

All metadata is derived from the StructureDefinition JSON itself. The lowercase `id` field
from the StructureDefinition is used as the profile's unique identifier and lookup key.
To use the uploaded profile with `/lang2fhir/create`, pass this id as the `resource` parameter.

Uploads will be rejected if:
- A built-in profile (US Core, PhenoML HPO, or R4 base) already exists with the same id, or the id starts with a reserved prefix (`us-core-`, `phenoml-hpo-`)
- A custom profile with the same id has already been uploaded
- A custom profile with the same url has already been uploaded
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.upload_profile(
    profile="eyJyZXNvdXJjZVR5cGUiOiJTdHJ1Y3R1cmVEZWZpbml0aW9uIiwiaWQiOiJjdXN0b20tcGF0aWVudCIsInVybCI6Imh0dHA6Ly9waGVub21sLmNvbS9maGlyL1N0cnVjdHVyZURlZmluaXRpb24vY3VzdG9tLXBhdGllbnQiLCJuYW1lIjoiQ3VzdG9tUGF0aWVudCIsInN0YXR1cyI6ImFjdGl2ZSIsImZoaXJWZXJzaW9uIjoiNC4wLjEiLCJraW5kIjoicmVzb3VyY2UiLCJhYnN0cmFjdCI6ZmFsc2UsInR5cGUiOiJQYXRpZW50IiwiYmFzZURlZmluaXRpb24iOiJodHRwOi8vaGw3Lm9yZy9maGlyL1N0cnVjdHVyZURlZmluaXRpb24vUGF0aWVudCIsImRlcml2YXRpb24iOiJjb25zdHJhaW50Iiwic25hcHNob3QiOnsiZWxlbWVudCI6W3siaWQiOiJQYXRpZW50IiwicGF0aCI6IlBhdGllbnQiLCJtaW4iOjAsIm1heCI6IioifSx7ImlkIjoiUGF0aWVudC5uYW1lIiwicGF0aCI6IlBhdGllbnQubmFtZSIsIm1pbiI6MSwibWF4IjoiKiJ9XX19Cg==",
    implementation_guide="acme-cardiology",
    profile_context="When clinical text describes cardiology-specific findings, prefer this profile over the generic US Core Condition.",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request:** `ProfileUploadRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">document</a>(...) -> FhirResource</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Extracts text from a PDF, image, RTF, or XML/C-CDA document and converts it into a structured FHIR resource.

The complete JSON request body is limited to 32 MiB (33,554,432 bytes). The application enforces this whole-envelope limit, including base64-encoded document `content`.

**Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.document(
    version="R4",
    resource="questionnaire",
    content="JVBERi0xLjQKJeLjz9MK...(base64-encoded document bytes)",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version:** `str` — FHIR version to use
    
</dd>
</dl>

<dl>
<dd>

**resource:** `str` — Type of FHIR resource to create. Accepts any FHIR resource type or US Core profile name.
    
</dd>
</dl>

<dl>
<dd>

**content:** `str` 

Base64 encoded file content.
Supported file types: PDF (application/pdf), PNG (image/png), JPEG (image/jpeg), TIFF (image/tiff), RTF (application/rtf), XML/C-CDA (text/xml).
TIFF, RTF, and XML/C-CDA uploads are available on dedicated instances only.
File type is auto-detected from content magic bytes.
The decoded file must not exceed 20 MiB. RTF and XML/C-CDA documents whose extracted text exceeds 1 MiB are rejected.
Generic XML must include an XML declaration; C-CDA documents rooted at `ClinicalDocument` may omit it.
    
</dd>
</dl>

<dl>
<dd>

**config:** `typing.Optional[DocumentConfig]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir.<a href="src/phenoml/lang2fhir/client.py">document_multi</a>(...) -> DocumentMultiResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Extracts text from a PDF, image, RTF, or XML/C-CDA document and converts it into multiple FHIR resources,
returned as a transaction Bundle. Combines document text extraction with multi-resource detection.
Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
Resources are linked with proper references (e.g., Conditions reference the Patient).

The complete JSON request body is limited to 32 MiB (33,554,432 bytes). The application enforces this whole-envelope limit, including base64-encoded document `content`.

**Patient handling.** Every bundle contains exactly one Patient, and every clinical resource references it. When the document names its patient, the Patient is built from the document. When it names several patients, the Patient is the one `primary_patient` names, otherwise the one most of the document is about; the others are not represented as Patients. Otherwise it is built from `primary_patient` when supplied, or is an unidentified Patient carrying only a synthetic identifier. When the document names its patient, the `primary_patient` identifier is added to that Patient unless its name, birth date, or gender contradicts the document's; the response `message` says whether it was added or did not match.

**Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). Every Patient carries a synthetic identifier with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value`, so the bundle remains FHIR-valid and US Core conformant. A medical record number stated in the document is added with `system: "urn:phenoml:lang2fhir-document-mrn"`, and the `primary_patient` identifier is added as described above. Callers who need a tenant-specific namespace should rewrite these systems after extraction.

**Page classification.** When `config` sets neither `split_classifications` nor `page_filter`, pages classified as test requisition forms (lab or diagnostic order forms) are dropped before extraction and reported in `page_classifications`. Supplying either setting replaces this default.

**Split classifications (optional).** `config.split_classifications` is a caller-defined list, not a fixed taxonomy. Choose each classification `id` and write a natural-language `description` for the per-page classifier. For each page, the classifier assigns the best-matching classification or leaves the page ungrouped. Classifications with `operation: "group"` keep matching pages and label resources extracted from those pages; classifications with `operation: "drop"` remove matching pages before extraction. The `clinical` and `admin` ids in the example are illustrative, not a fixed set.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment
from phenoml.lang2fhir import DocumentConfig, SplitClassification

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir.document_multi(
    version="R4",
    content="JVBERi0xLjQKJeLjz9MK...(base64-encoded document bytes)",
    provider="medplum",
    config=DocumentConfig(
        split_classifications=[
            SplitClassification(
                id="clinical",
                description="Clinical notes, diagnoses, medications, observations, and patient demographics.",
                operation="group",
            ),
            SplitClassification(
                id="admin",
                description="Administrative boilerplate, insurance forms, and cover sheets.",
                operation="drop",
            )
        ],
    ),
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**version:** `str` — FHIR version to use
    
</dd>
</dl>

<dl>
<dd>

**content:** `str` 

Base64 encoded file content.
Supported file types: PDF (application/pdf), PNG (image/png), JPEG (image/jpeg), TIFF (image/tiff), RTF (application/rtf), XML/C-CDA (text/xml).
TIFF, RTF, and XML/C-CDA uploads are available on dedicated instances only.
File type is auto-detected from content magic bytes.
The decoded file must not exceed 20 MiB. RTF and XML/C-CDA documents whose extracted text exceeds 1 MiB are rejected.
Generic XML must include an XML declaration; C-CDA documents rooted at `ClinicalDocument` may omit it.
    
</dd>
</dl>

<dl>
<dd>

**provider:** `typing.Optional[str]` — Optional FHIR provider name for provider-specific profiles
    
</dd>
</dl>

<dl>
<dd>

**primary_patient:** `typing.Optional[PrimaryPatient]` — Context for the patient the document is primarily about. When the document does not name its patient, the bundle's Patient is built from these fields. When it does, the identifier is added to that Patient unless its name, birth date, or gender contradicts these fields.
    
</dd>
</dl>

<dl>
<dd>

**patient_reference:** `typing.Optional[PatientReference]` — Deprecated compatibility alias for primary_patient.identifier. Cannot be combined with primary_patient.
    
</dd>
</dl>

<dl>
<dd>

**implementation_guide:** `typing.Optional[str]` — Implementation Guide to generate resources under. `us_core` (the default) and `phenoml_hpo` select a built-in guide. Any other value is a custom Implementation Guide name: its profiles are included alongside the US Core profiles, which are always the base layer. A custom name that matches no uploaded Implementation Guide returns 404.
    
</dd>
</dl>

<dl>
<dd>

**detection_effort:** `typing.Optional[DocumentMultiRequestDetectionEffort]` — Deprecated and ignored: both values produce the same result. This field will be removed in a future release.
    
</dd>
</dl>

<dl>
<dd>

**validation_method:** `typing.Optional[DocumentMultiRequestValidationMethod]` — FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips.
    
</dd>
</dl>

<dl>
<dd>

**config:** `typing.Optional[DocumentConfig]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Lang2FhirBatch
<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">list</a>(...) -> JobListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a page of the instance's batch jobs, newest first, without
per-job counts. Jobs are shared across the instance's credentials, so
this lists every batch job on the instance, not just the calling
credential's.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.list(
    cursor="cursor",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**cursor:** `typing.Optional[str]` — Opaque pagination cursor from a previous page's next_cursor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Page size. Defaults to 20; values above 100 are clamped to 100.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">create</a>(...) -> BatchJob</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Opens an empty job; upload items, then finalize it to start processing.

`request_id` makes creation idempotent: a retry returns the original
job. A token is released when its job is canceled or fails before
finalization; otherwise it continues to resolve to that job.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.create(
    request_id="submit-2025-09-02-batch-001",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_id:** `typing.Optional[str]` 

Optional client idempotency token (at most 256 UTF-8 bytes). A
retried create with the same token returns the original job instead
of opening a second one.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">upload_item</a>(...) -> UploadItemResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Stores one multipart item. Set **either** `document` with a raw `file`,
or JSON-only `create`.

Set exactly one JSON object. `document` requires `file`; `create`
forbids it. Violations return `400`.

Upload validates only the envelope. Endpoint request validation happens
during processing: decoding failures are `invalid_input`; other pipeline
failures are `processing_failed`.

Use `request_id` for every upload so retries replace the same item.
`deduplicated` is true only for an unchanged payload; a changed payload
overwrites the item and returns false.

Uploads return `409` after finalization or at the item limit, and `413`
when the item is too large.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.upload_item(
    job_id="job_id",
    file="example_file",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**document:** `typing.Optional[typing.Dict[str, typing.Any]]` 

The JSON body of `POST /lang2fhir/document/multi`, **without**
its base64 `content` field — the uploaded `file` supplies the
content. Accepts that endpoint's fields (`version`, `provider`,
`primary_patient`, `patient_reference` (deprecated), `implementation_guide`, `detection_effort` (deprecated),
`validation_method`, `config`). This is the **multi**-resource
body: it has no single-`resource` field, and the item's result
is a `DocumentMultiResponse` (a Bundle of resources). Mutually
exclusive with `create`; requires `file`. Do not combine
`primary_patient` with `patient_reference`.
    
</dd>
</dl>

<dl>
<dd>

**create:** `typing.Optional[typing.Dict[str, typing.Any]]` 

The JSON body of `POST /lang2fhir/create/multi`. Accepts that
endpoint's fields (`text`, `version`, `provider`,
`primary_patient`, `patient_reference` (deprecated), `implementation_guide`, `detection_effort` (deprecated),
`validation_method`, `resource_review`, `small_note`). This is the
**multi**-resource body: it has no single-`resource` field, and
the item's result is a `CreateMultiResponse` (a Bundle of
resources). Mutually exclusive with `document`; must **not** be
accompanied by a `file`. Do not combine `primary_patient` with
`patient_reference`.
    
</dd>
</dl>

<dl>
<dd>

**file:** `typing.Optional[core.File]` 

The document's file content (PDF, PNG, JPEG, TIFF, RTF, or
XML/C-CDA). The document pipeline accepts files up to 20 MiB;
an upload that passes the storage cap but exceeds this limit
fails during processing. RTF and XML/C-CDA documents whose
extracted text exceeds 1 MiB also fail during processing.
Generic XML must include an XML declaration; C-CDA documents
rooted at `ClinicalDocument` may omit it.
Required with `document`; forbidden with `create`.
    
</dd>
</dl>

<dl>
<dd>

**request_id:** `typing.Optional[str]` 

Optional idempotency token (at most 256 UTF-8 bytes).
Re-uploading under the same token overwrites the same item
instead of adding a new one. The token is scoped to this job;
the same token in another job is independent and creates a
separate item.
    
</dd>
</dl>

<dl>
<dd>

**id:** `typing.Optional[str]` 

Optional caller-supplied correlation label (at most 512 UTF-8
bytes), echoed back on status and result listings so you can
match the server's item_id to your own record.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">finalize</a>(...) -> BatchJob</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Seals the job's item set and starts processing. Takes no request body.
Finalize is idempotent: a retried finalize succeeds again.

If a previous upload did not complete, finalize returns a `409`; re-send
the missing upload (with the same `request_id`), then finalize.
Finalizing a job with no items is a `400`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.finalize(
    job_id="job_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">cancel</a>(...) -> BatchJob</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Drives a job to the terminal `canceled` state on request. Takes no
request body.

Cancel does not delete the job: the job record and any results already
produced are preserved for the normal retention window, the same as a
`completed` or `failed` job. Items stop being processed and keep the state
they held at cancellation, so a canceled job's `counts` may show
unfinished items that never resolve.

Cancel is idempotent: canceling an already-`canceled` job returns `200`
with the job. Canceling a job that has already `completed` or `failed` is
a `409`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.cancel(
    job_id="job_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">get</a>(...) -> JobDetailResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a job's record, its per-status item counts, and one page of
per-item statuses.

Items are listed in a stable order that is not upload order and is the
same across pages. Match each entry to your own records by its `id`
(your correlation label) or `item_id` (from the upload response),
never by position.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.get(
    job_id="job_id",
    cursor="cursor",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**cursor:** `typing.Optional[str]` — Opaque pagination cursor from a previous page's next_cursor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Page size for the item-status page. Defaults to 20; values above 100 are clamped to 100.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">get_results</a>(...) -> ResultsPageResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

A lighter status page. Returns the same per-item status entries as
`GET /lang2fhir/batch/{job_id}`, but without the job record or counts,
and the entries carry `result_size` rather than any result content. Use
each entry's `item_id` to fetch that item's result from
`GET /lang2fhir/batch/{job_id}/results/{item_id}`.

Entries are listed in a stable order that is not upload order and is
the same across pages. Match each entry to your own records by its `id`
(your correlation label) or `item_id` (from the upload response),
never by position.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.get_results(
    job_id="job_id",
    cursor="cursor",
    limit=1,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**cursor:** `typing.Optional[str]` — Opaque pagination cursor from a previous page's next_cursor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `typing.Optional[int]` — Page size. Defaults to 20; values above 100 are clamped to 100.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.lang2fhir_batch.<a href="src/phenoml/lang2fhir_batch/client.py">get_result</a>(...) -> typing.Dict[str, typing.Any]</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Streams one item's stored result bytes verbatim as `application/json`.
The body is the response the item's synchronous multi endpoint would have
returned — a `DocumentMultiResponse` for a document item or a
`CreateMultiResponse` for a create item.

Only a succeeded item has a result: an item that has not succeeded
(pending, processing, or failed) is a `409`, and a result that has
expired is a `404`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.lang2fhir_batch.get_result(
    job_id="job_id",
    item_id="item_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**job_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**item_id:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Profiles
<details><summary><code>client.profiles.profiles.<a href="src/phenoml/profiles/profiles/client.py">list</a>(...) -> ProfileListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns metadata for every custom (uploaded) FHIR profile on this
instance, across all implementation guides. The full StructureDefinition
JSON is omitted from each entry; fetch a single profile by id to retrieve it.

The `url` query parameter filters by canonical URL. The canonical URL is the
stable key other platform features use to reference a profile (FHIR's
`meta.profile`, `baseDefinition`), since StructureDefinition ids are only
unique within a package. An unpinned `url` filter returns metadata for
the profile's current StructureDefinition. Pinned `url|version` filters
resolve a retained version when present; otherwise they can fall back to
the profile's current StructureDefinition, whose content can change
through the profile update endpoint. A non-matching filter returns an
empty list, not a 404.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.profiles.list(
    url="http://phenoml.com/fhir/StructureDefinition/custom-patient|1.0.0",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**url:** `typing.Optional[str]` — Filter by canonical URL. Accepts the FHIR pinned form `url|version`; without a version pin, returns the profile's current StructureDefinition metadata.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.profiles.<a href="src/phenoml/profiles/profiles/client.py">create</a>(...) -> ProfileSummary</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a custom profile from a FHIR StructureDefinition supplied as a JSON
object. Metadata such as version, resource type, and url is read from the
StructureDefinition; the lowercase StructureDefinition id becomes the
profile's lookup key. When id is omitted, a random UUID is assigned.
Optionally group the profile under a named implementation guide.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.profiles.create(
    structure_definition={
        "resourceType": "StructureDefinition",
        "id": "custom-patient",
        "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
        "name": "CustomPatient",
        "status": "active",
        "fhirVersion": "4.0.1",
        "kind": "resource",
        "abstract": False,
        "type": "Patient",
        "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
        "derivation": "constraint",
        "snapshot": {"element": [{"id": "Patient", "path": "Patient", "min": 0, "max": "*"}]}
    },
    implementation_guide="acme-cardiology",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request:** `ProfileUploadRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.profiles.<a href="src/phenoml/profiles/profiles/client.py">get</a>(...) -> ProfileGetResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single custom profile by id, including its full StructureDefinition
JSON.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.profiles.get(
    id="custom-patient",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.profiles.<a href="src/phenoml/profiles/profiles/client.py">update</a>(...) -> ProfileSummary</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Replaces an existing custom profile with a new StructureDefinition. The
`id` path parameter is authoritative: if the StructureDefinition includes
an `id` it must match the path parameter, and if it omits one the path
parameter is used. The FHIR resource type of the profile cannot change.
When `implementation_guide` is omitted, the profile keeps its existing
implementation guide. A retained version string is allowed only when
re-submitting the profile's current version with an unchanged
StructureDefinition; otherwise it returns a conflict. While the profile
has retained versions, its
canonical URL cannot be changed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.profiles.update(
    id="custom-patient",
    structure_definition={
        "resourceType": "StructureDefinition",
        "id": "custom-patient",
        "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
        "name": "CustomPatient",
        "status": "active",
        "fhirVersion": "4.0.1",
        "kind": "resource",
        "abstract": False,
        "type": "Patient",
        "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
        "derivation": "constraint",
        "snapshot": {"element": [{"id": "Patient", "path": "Patient", "min": 0, "max": "*"}]}
    },
    implementation_guide="acme-cardiology",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**request:** `ProfileUploadRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.profiles.<a href="src/phenoml/profiles/profiles/client.py">delete</a>(...)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Permanently deletes a custom profile by id. This also deletes all retained
versions for that profile so the canonical URL can be reused by a later
upload.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.profiles.delete(
    id="custom-patient",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Profiles Versions
<details><summary><code>client.profiles.versions.<a href="src/phenoml/profiles/versions/client.py">list</a>(...) -> ProfileVersionListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns retained versions for a custom profile.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.versions.list(
    id="custom-patient",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.versions.<a href="src/phenoml/profiles/versions/client.py">create</a>(...) -> ProfileSummary</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Adds an immutable StructureDefinition version to a custom profile. If
the profile does not exist, it is created from the submitted version.
The StructureDefinition must include a non-empty `version`; its
canonical URL and resource type must match the profile when one already
exists. If it includes an `id`, that id must match the path parameter;
if it omits `id`, the path parameter is used. Profiles created through
this endpoint are grouped under `custom`. Posting the profile's current
StructureDefinition unchanged retains it as a version.
Version strings may contain letters, numbers, and the punctuation
characters `.`, `_`, `~`, `+`, and `-`; they cannot be exactly `.` or
`..`. Each profile can retain up to 250 versions; delete old
versions before adding more.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.versions.create(
    id="custom-patient",
    request={
        "key": "value"
    },
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**request:** `ProfileVersionCreateRequest` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.versions.<a href="src/phenoml/profiles/versions/client.py">get</a>(...) -> ProfileGetResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns metadata and the full StructureDefinition for one retained
version. The returned StructureDefinition's id is the profile id. The
path version is the authored `StructureDefinition.version` value.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.versions.get(
    id="custom-patient",
    version="2.0.0",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**version:** `str` — The authored StructureDefinition.version. It may contain letters, numbers, and the punctuation characters `.`, `_`, `~`, `+`, and `-`; it cannot be exactly `.` or `..`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.profiles.versions.<a href="src/phenoml/profiles/versions/client.py">delete</a>(...)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes one retained version from a custom profile. The path
version is the authored `StructureDefinition.version` value.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.profiles.versions.delete(
    id="custom-patient",
    version="2.0.0",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — The lowercase StructureDefinition id of the custom profile.
    
</dd>
</dl>

<dl>
<dd>

**version:** `str` — The authored StructureDefinition.version. It may contain letters, numbers, and the punctuation characters `.`, `_`, `~`, `+`, and `-`; it cannot be exactly `.` or `..`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Templates
<details><summary><code>client.summary.templates.<a href="src/phenoml/summary/templates/client.py">list</a>() -> ListResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves all summary templates for the authenticated user
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.summary.templates.<a href="src/phenoml/summary/templates/client.py">create</a>(...) -> CreateSummaryTemplateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a summary template from an example using LLM function calling
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.create(
    name="Discharge Summary",
    example_summary="Patient John Doe, age 45, was admitted on 2024-01-10 with Type 2 Diabetes. Discharged on 2024-01-15 with Metformin 500mg BID.",
    target_resources=[
        "Patient",
        "Condition",
        "MedicationRequest"
    ],
    mode="narrative",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Name of the template
    
</dd>
</dl>

<dl>
<dd>

**example_summary:** `str` — Example summary note to generate template from
    
</dd>
</dl>

<dl>
<dd>

**target_resources:** `typing.List[str]` — List of target FHIR resources
    
</dd>
</dl>

<dl>
<dd>

**mode:** `str` — Template mode (stored with the template)
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` — Description of the template
    
</dd>
</dl>

<dl>
<dd>

**example_fhir_data:** `typing.Optional[typing.Dict[str, typing.Any]]` — Optional example FHIR data that corresponds to the example summary
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.summary.templates.<a href="src/phenoml/summary/templates/client.py">get</a>(...) -> GetResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a specific summary template
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.get(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Template ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.summary.templates.<a href="src/phenoml/summary/templates/client.py">update</a>(...) -> UpdateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing summary template
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.update(
    id="id",
    name="Discharge Summary",
    template="Patient {{Patient.name[0].text}} was discharged on {{Encounter[0].period.end}} with {{MedicationRequest[0].medicationCodeableConcept.coding[0].display}} {{MedicationRequest[0].dosageInstruction[0].text}}.",
    target_resources=[
        "Patient",
        "Encounter",
        "MedicationRequest"
    ],
    mode="narrative",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Template ID
    
</dd>
</dl>

<dl>
<dd>

**name:** `str` 
    
</dd>
</dl>

<dl>
<dd>

**template:** `str` — Updated template with placeholders
    
</dd>
</dl>

<dl>
<dd>

**target_resources:** `typing.List[str]` 
    
</dd>
</dl>

<dl>
<dd>

**mode:** `str` — Template mode
    
</dd>
</dl>

<dl>
<dd>

**description:** `typing.Optional[str]` 
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.summary.templates.<a href="src/phenoml/summary/templates/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a summary template
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.templates.delete(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — Template ID
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Summary
<details><summary><code>client.summary.<a href="src/phenoml/summary/client.py">create</a>(...) -> CreateSummaryResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a summary from FHIR resources using one of three modes:
- **narrative**: Uses a template to substitute FHIR data into placeholders (requires template_id)
- **flatten**: Flattens FHIR resources into a searchable format for RAG/search (no template needed)
- **ips**: Generates an International Patient Summary (IPS) narrative per ISO 27269/HL7 FHIR IPS IG. Requires a Bundle with exactly one Patient resource (returns 400 error if no Patient or multiple Patients are present). Automatically filters resources to those referencing the patient and generates sections for allergies, medications, problems, immunizations, procedures, and vital signs.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.summary.create(
    mode="narrative",
    template_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    fhir_resources={
        "resourceType": "Bundle",
        "type": "collection",
        "entry": [{"resource": {"resourceType": "Patient", "name": [{"given": ["John"], "family": "Doe"}], "gender": "male", "birthDate": "1979-03-15"}}, {"resource": {"resourceType": "Condition", "code": {"text": "Type 2 Diabetes Mellitus"}, "onsetDateTime": "2024-01-15"}}]
    },
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**fhir_resources:** `typing.Dict[str, typing.Any]` 

FHIR resources (single resource or Bundle).
For IPS mode, must be a Bundle containing exactly one Patient resource with at least one
identifier (id, fullUrl, or identifier field). Returns an error if no Patient is found,
if multiple Patients are present, or if the Patient has no identifiers. Resources are
automatically filtered to only include those referencing the patient.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `typing.Optional[CreateSummaryRequestMode]` 

Summary generation mode:
- narrative: Substitute FHIR data into a template (requires template_id)
- flatten: Flatten FHIR resources for RAG/search (no template needed)
- ips: Generate International Patient Summary (IPS) narrative per ISO 27269/HL7 FHIR IPS IG
    
</dd>
</dl>

<dl>
<dd>

**template_id:** `typing.Optional[str]` — ID of the template to use (required for narrative mode)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Tools
<details><summary><code>client.tools.<a href="src/phenoml/tools/client.py">create_fhir_resource</a>(...) -> Lang2FhirAndCreateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language to FHIR resource and optionally stores it in a FHIR server
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.create_fhir_resource(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    resource="condition-encounter-diagnosis",
    text="Patient has severe persistent asthma with acute exacerbation",
    provider="550e8400-e29b-41d4-a716-446655440000",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**resource:** `Lang2FhirAndCreateRequestResource` — Type of FHIR resource to create. Use 'auto' for automatic resource type detection, or specify a supported US Core profile.
    
</dd>
</dl>

<dl>
<dd>

**text:** `str` — Natural language text to convert to FHIR resource
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**provider:** `typing.Optional[str]` — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.<a href="src/phenoml/tools/client.py">create_fhir_resources_multi</a>(...) -> Lang2FhirAndCreateMultiResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Extracts multiple FHIR resources from natural language text and stores them in a FHIR server.
Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
Resources are linked with proper references and submitted as a transaction bundle.
For FHIR servers that don't auto-resolve urn:uuid references, this endpoint will automatically
resolve them via PUT requests after the initial bundle creation.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.create_fhir_resources_multi(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="John Smith, 45-year-old male, diagnosed with Type 2 Diabetes. Prescribed Metformin 500mg twice daily.",
    version="R4",
    provider="medplum",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text containing multiple clinical concepts to extract
    
</dd>
</dl>

<dl>
<dd>

**provider:** `str` — FHIR provider ID or name
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**version:** `typing.Optional[str]` — FHIR version to use
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.<a href="src/phenoml/tools/client.py">search_fhir_resources</a>(...) -> Lang2FhirAndSearchResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Converts natural language to FHIR search parameters and executes search in FHIR server
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.search_fhir_resources(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="Find all appointments for patient John Doe next week",
    count=10,
    provider="550e8400-e29b-41d4-a716-446655440000",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text to convert to FHIR search parameters
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**patient_id:** `typing.Optional[str]` — Patient ID to filter results
    
</dd>
</dl>

<dl>
<dd>

**count:** `typing.Optional[int]` — Maximum number of results to return
    
</dd>
</dl>

<dl>
<dd>

**provider:** `typing.Optional[str]` — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.<a href="src/phenoml/tools/client.py">analyze_cohort</a>(...) -> CohortResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Uses LLM to extract search concepts from natural language and builds patient cohorts with inclusion/exclusion criteria
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.analyze_cohort(
    phenoml_on_behalf_of="Patient/550e8400-e29b-41d4-a716-446655440000",
    phenoml_fhir_provider="550e8400-e29b-41d4-a716-446655440000:eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c...",
    text="female patients over 20 with diabetes but not hypertension",
    provider="550e8400-e29b-41d4-a716-446655440000",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**text:** `str` — Natural language text describing the patient cohort criteria
    
</dd>
</dl>

<dl>
<dd>

**provider:** `str` — FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum)
    
</dd>
</dl>

<dl>
<dd>

**phenoml_on_behalf_of:** `typing.Optional[str]` 

Optional header for on-behalf-of authentication. Used when making requests on behalf of another user or entity.
Must be in the format: Patient/{uuid} or Practitioner/{uuid}
    
</dd>
</dl>

<dl>
<dd>

**phenoml_fhir_provider:** `typing.Optional[str]` 

Optional header for FHIR provider authentication. Contains credentials in the format {fhir_provider_id}:{oauth2_token}.
Multiple FHIR provider integrations can be provided as comma-separated values.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## MCP Servers
<details><summary><code>client.tools.mcp_servers.<a href="src/phenoml/tools/mcp_servers/client.py">create</a>(...) -> McpServerResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new MCP server
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.create(
    name="My MCP Server",
    mcp_server_url="https://mcp.example.com",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Name of the MCP server
    
</dd>
</dl>

<dl>
<dd>

**mcp_server_url:** `str` — URL of the MCP server
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.mcp_servers.<a href="src/phenoml/tools/mcp_servers/client.py">list</a>() -> McpServerResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all MCP servers for a specific user
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.list()

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.mcp_servers.<a href="src/phenoml/tools/mcp_servers/client.py">get</a>(...) -> McpServerResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Gets a MCP server by ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.get(
    mcp_server_id="mcp_server_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**mcp_server_id:** `str` — ID of the MCP server to retrieve
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.mcp_servers.<a href="src/phenoml/tools/mcp_servers/client.py">delete</a>(...) -> McpServerResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a MCP server by ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_servers.delete(
    mcp_server_id="mcp_server_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**mcp_server_id:** `str` — ID of the MCP server to delete
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Tools McpTools
<details><summary><code>client.tools.mcp_tools.<a href="src/phenoml/tools/mcp_tools/client.py">list</a>(...) -> McpServerToolResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all MCP server tools for a specific MCP server
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.list(
    mcp_server_id="mcp_server_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**mcp_server_id:** `str` — ID of the MCP server to list tools for
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.mcp_tools.<a href="src/phenoml/tools/mcp_tools/client.py">get</a>(...) -> McpServerToolResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Gets a MCP server tool by ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.get(
    mcp_server_tool_id="mcp_server_tool_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**mcp_server_tool_id:** `str` — ID of the MCP server tool to retrieve
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.tools.mcp_tools.<a href="src/phenoml/tools/mcp_tools/client.py">delete</a>(...) -> McpServerToolResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a MCP server tool by ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.tools.mcp_tools.delete(
    mcp_server_tool_id="mcp_server_tool_id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**mcp_server_tool_id:** `str` — ID of the MCP server tool to delete
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Voice
<details><summary><code>client.voice.voice.<a href="src/phenoml/voice/voice/client.py">transcribe</a>(...) -> TranscribeResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Transcribes an uploaded audio recording and returns the transcript.
Send the raw audio bytes as the request body; the audio format is
detected automatically (WAV, FLAC, MP3, OGG/WebM Opus).

The raw audio request body is limited to 32 MiB. Supports up to ~5
minutes of audio per request. This duration limit is independent of file
size or format, so a compressed recording within the body-size limit can
still be rejected for being too long. Pair the transcript with a
downstream text step (e.g. `POST /lang2fhir/create`) to turn it into a
FHIR resource.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
client.voice.voice.transcribe(...)
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**request:** `typing.Union[bytes, typing.Iterator[bytes], typing.AsyncIterator[bytes]]` — Raw audio bytes (WAV, FLAC, MP3, or OGG/WebM Opus), up to 32 MiB.
    
</dd>
</dl>

<dl>
<dd>

**language:** `typing.Optional[typing.Union[str, typing.Sequence[str]]]` — BCP-47 language tag, repeatable for up to 4 candidate languages. Defaults to `en-US`.
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Workflows
<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">list</a>(...) -> ListWorkflowsResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves all workflow definitions for the authenticated user
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.list(
    verbose=True,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**verbose:** `typing.Optional[bool]` — If true, includes full workflow implementation details in workflow_details field
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">create</a>(...) -> CreateWorkflowResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new workflow definition with graph generation from workflow instructions
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.create(
    verbose=True,
    name="Patient Data Mapping Workflow",
    workflow_instructions="Given diagnosis data, find the patient and create a condition record linked to their encounter",
    sample_data={
        "patient_last_name": "Rippin",
        "patient_first_name": "Clay",
        "diagnosis_code": "I10",
        "encounter_date": "2024-01-15"
    },
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `str` — Human-readable name for the workflow
    
</dd>
</dl>

<dl>
<dd>

**workflow_instructions:** `str` — Natural language instructions that define the workflow logic
    
</dd>
</dl>

<dl>
<dd>

**sample_data:** `typing.Dict[str, typing.Any]` — Sample data to use for workflow graph generation
    
</dd>
</dl>

<dl>
<dd>

**fhir_provider_id:** `CreateWorkflowRequestFhirProviderId` — FHIR provider ID(s) - must be valid UUID(s) from existing FHIR providers
    
</dd>
</dl>

<dl>
<dd>

**verbose:** `typing.Optional[bool]` — If true, includes full workflow implementation details in workflow_details field
    
</dd>
</dl>

<dl>
<dd>

**dynamic_generation:** `typing.Optional[bool]` — Enable dynamic lang2fhir calls instead of pre-populated templates
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">get</a>(...) -> GetResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Retrieves a workflow definition by its ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.get(
    id="id",
    verbose=True,
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — ID of the workflow to retrieve
    
</dd>
</dl>

<dl>
<dd>

**verbose:** `typing.Optional[bool]` — If true, includes full workflow implementation details in workflow_details field
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">update</a>(...) -> UpdateResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing workflow definition
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.update(
    id="id",
    verbose=True,
    name="Patient Data Mapping Workflow (v2)",
    workflow_instructions="Given diagnosis data, find the patient and create a condition record linked to their encounter",
    sample_data={
        "patient_last_name": "Rippin",
        "patient_first_name": "Clay",
        "diagnosis_code": "I10",
        "encounter_date": "2024-01-15"
    },
    fhir_provider_id="550e8400-e29b-41d4-a716-446655440000",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — ID of the workflow to update
    
</dd>
</dl>

<dl>
<dd>

**name:** `str` — Human-readable name for the workflow
    
</dd>
</dl>

<dl>
<dd>

**workflow_instructions:** `str` — Natural language instructions that define the workflow logic
    
</dd>
</dl>

<dl>
<dd>

**sample_data:** `typing.Dict[str, typing.Any]` — Sample data to use for workflow graph generation
    
</dd>
</dl>

<dl>
<dd>

**fhir_provider_id:** `UpdateWorkflowRequestFhirProviderId` — FHIR provider ID(s) - must be valid UUID(s) from existing FHIR providers
    
</dd>
</dl>

<dl>
<dd>

**verbose:** `typing.Optional[bool]` — If true, includes full workflow implementation details in workflow_details field
    
</dd>
</dl>

<dl>
<dd>

**dynamic_generation:** `typing.Optional[bool]` — Enable dynamic lang2fhir calls instead of pre-populated templates
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">delete</a>(...) -> DeleteResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a workflow definition by its ID
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.delete(
    id="id",
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — ID of the workflow to delete
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.workflows.<a href="src/phenoml/workflows/client.py">execute</a>(...) -> ExecuteWorkflowResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Executes a workflow with provided input data and returns results
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```python
from phenoml import PhenomlClient
from phenoml.environment import PhenomlClientEnvironment

client = PhenomlClient(
    client_id="<clientId>",
    client_secret="<clientSecret>",
    environment=PhenomlClientEnvironment.DEFAULT,
)

client.workflows.execute(
    id="7a8b9c0d-1234-5678-abcd-ef9876543210",
    input_data={
        "patient_last_name": "Johnson",
        "patient_first_name": "Mary",
        "diagnosis_code": "M79.3",
        "encounter_date": "2024-03-20"
    },
)

```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `str` — ID of the workflow to execute
    
</dd>
</dl>

<dl>
<dd>

**input_data:** `typing.Dict[str, typing.Any]` — Input data for workflow execution
    
</dd>
</dl>

<dl>
<dd>

**preview:** `typing.Optional[bool]` — If true, create operations return mock resources instead of persisting to the FHIR server
    
</dd>
</dl>

<dl>
<dd>

**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>