Metadata-Version: 2.4
Name: valmar
Version: 1.0.0
Summary: Python SDK for the Valmar platform
Project-URL: Homepage, https://docs.getvalmar.com
Project-URL: Documentation, https://docs.getvalmar.com
Project-URL: Source, https://github.com/TheValmarAI/valmar-python
Author: Valmar
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,enterprise-context,knowledge,sdk,valmar
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: ai
Requires-Dist: pydantic-ai>=0.1; extra == 'ai'
Description-Content-Type: text/markdown

# valmar

Python SDK for the Valmar platform.

Documentation: https://docs.getvalmar.com

Source: https://github.com/TheValmarAI/valmar-python

License: Apache-2.0

## Installation

```bash
uv add valmar
```

## Quick start

```python
from valmar import Valmar

client = Valmar(
    api_key="valmr_proj_sk_...",
    base_url="https://your-valmar-deployment.example.com",
    organization_id="your-org-id",
    project_id="your-project-id",
)
```

`base_url` is required because Valmar is deployed per customer. Use the base URL for your own Valmar deployment.

## Search context

Find relevant saved knowledge across the configured project.

```python
results = client.context.search("deployment process")

for hit in results.hits:
    resource = client.context.read(hit.reference)
    print(f"{hit.title} ({hit.score})")
    print(resource.content_md)

    trace = client.context.trace(hit.reference)
    print(trace.source_thread_ids)
```

## Create a context request

Create a context request that gets routed to the right people in your organization.

```python
handle = client.context_requests.create(
    "How do we handle database migrations in production?",
    background_context="Planning a schema change for the orders table",
    hidden_metadata={"external_case_id": "CASE-4821"},
)

print(f"Request created: {handle.context_request_id}")
print(f"Status: {handle.status}")

request = client.context_requests.get(handle.context_request_id)
if request.status == "completed":
    print(request.result_summary)
    print(request.hidden_metadata["external_case_id"])
```

`hidden_metadata` is an immutable string-to-string map copied to every
unstructured context snippet saved from the request. It is returned by the API
and SDK for client-side matching, but is not exposed through MCP or to Valmar AI agents.

## List and import people

```python
from valmar import CreatePersonInput

people = client.people.list()

result = client.people.import_bulk(
    [
        CreatePersonInput(
            email="ada@example.com",
            display_name="Ada Lovelace",
            timezone="UTC",
            title="Principal Engineer",
        )
    ]
)
```

## Run Knowledge Gap analysis

Use the active connection configured by a project administrator.

```python
overview = client.knowledge_gaps.overview()
run = client.knowledge_gaps.start_run(custom_instructions="Focus on incident workflows")

# After the run completes:
ranking = client.knowledge_gaps.get_run_artifact(run.run_id, "ranking.json")
submissions = client.knowledge_gaps.submit_ranked_gaps(run.run_id, gap_ranks=[1, 2])
```

## Context manager

```python
with Valmar(
    api_key="valmr_proj_sk_...",
    base_url="https://your-valmar-deployment.example.com",
    organization_id="your-org-id",
    project_id="your-project-id",
) as client:
    results = client.context.search("onboarding process")
```

## Error handling

The SDK raises `httpx.HTTPStatusError` for non-2xx responses.

```python
import httpx

try:
    client.context.search("test")
except httpx.HTTPStatusError as e:
    print(f"API error {e.response.status_code}: {e.response.text}")
```
