Metadata-Version: 2.4
Name: guidelight
Version: 0.4.0
Summary: A library for developing task-oriented AI systems that integrate with Endeavor.
Home-page: https://github.com/rotationalio/guidelight
Download-URL: https://github.com/rotationalio/guidelight/tarball/v0.4.0
Author: Rotational Labs
Author-email: support@rotational.io
Maintainer: Rotational Labs
Maintainer-email: support@rotational.io
License: BSD 3-Clause
Project-URL: Documentation, https://github.com/rotationalio/guidelight
Project-URL: Download, https://github.com/rotationalio/guidelight/tarball/v0.4.0
Project-URL: Source, https://github.com/rotationalio/guidelight
Project-URL: Tracker, https://github.com/rotationalio/guidelight/issues
Keywords: guidelight,ai,endeavor,api client,tasks,workflows
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10, <4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ciso8601==2.3.3
Requires-Dist: PyJWT==2.10.1
Requires-Dist: python-dotenv==1.1.1
Requires-Dist: requests==2.32.5
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Guidelight

**A library for developing task-oriented AI systems that integrate with Endeavor.**

## Getting Started

Install Guidelight:

```console
pip install guidelight
```

Configure an Endeavor API key:

```dotenv
ENDEAVOR_URL=https://guidelight.dev
ENDEAVOR_AUTH_URL=https://auth.guidelight.dev
ENDEAVOR_CLIENT_ID=your-client-id
ENDEAVOR_CLIENT_SECRET=your-client-secret
```

`ENDEAVOR_AUTH_URL` is the authentication service's base URL. Guidelight adds the `/v1/authenticate` path.

Create a high-level Endeavor SDK:

```python
import guidelight as gdl

endeavor = gdl.connect()
print(endeavor.status())
```

Use `gdl.client()` when direct access to the low-level HTTP client is needed:

```python
client = gdl.client()
print(client.status())
```

The high-level SDK also exposes its authenticated client:

```python
client = endeavor.client
```

## Low-level Client

The low-level client accepts endpoint path components and automatically adds
the configured API version.

### GET

```python
agents = client.get(
    "agents",
    query={"page_size": 10, "offset": 0},
)
```

### POST

```python
agent = client.post(
    {
        "name": "Demo Support Agent",
        "description": "A demonstration Agent.",
    },
    "agents",
)
```

### PUT

```python
updated_agent = client.put(
    {
        "name": "Updated Demo Support Agent",
        "description": "An updated demonstration Agent.",
    },
    "agents",
    "<agent-ulid>",
)
```

### PATCH

Use PATCH only with an endpoint that supports partial updates:

```python
environment = client.patch(
    {
        "description": "Updated development environment.",
    },
    "environments",
    "<environment-ulid-or-slug>",
)
```

### DELETE

```python
client.delete("agents", "<agent-ulid>")
```

### Execute a deployed Task

Execute by Agent and Task slug or ID:

```python
result = client.execute(
    "demo-support-agent",
    "summarize-message",
    context={
        "message": "Summarize this example customer message.",
    },
)
```

Select a deployed Release by Environment and semantic Version:

```python
result = client.execute(
    "demo-support-agent",
    "summarize-message",
    context={"message": "Summarize this text."},
    environment="production",
    version="1.2.3",
)
```

Execute using a complete deployed-task URL. **NOTE:** Cross-origin URLs are rejected unless explicitly enabled.

```python
result = client.execute(
    deployed_task_url=(
        "https://guidelight.dev/api/"
        "demo-support-agent/summarize-message"
    ),
    context={"message": "Summarize this text."},
)
```


Upload a file using multipart form data:

```python
with open("example.pdf", "rb") as document:
    result = client.execute(
        "demo-document-agent",
        "extract-document-text",
        context={"instruction": "Extract the important details."},
        files={
            "example.pdf": document,
        },
    )
```

`Client.execute()` returns the decoded JSON body or raw response bytes by
default. Pass `raw=True` when response headers and the underlying
`requests.Response` are needed.

## High-level Endeavor SDK

The high-level SDK provides typed resource operations and decodes deployed-task
responses according to their response content type.

### List and retrieve Agents

```python
page = endeavor.agents.list(
    page_size=10,
    offset=0,
    order_by="name",
)

for agent in page:
    print(agent.id, agent.name, agent.slug)

agent = endeavor.agents.get("demo-support-agent")
```

Iterate across all Agent pages:

```python
for agent in endeavor.agents.iterate(page_size=25):
    print(agent.name)
```

### Create, update, and delete an Agent

```python
agent = endeavor.agents.create(
    name="Demo Support Agent",
    description="A temporary demonstration Agent.",
)

agent = endeavor.agents.update(
    agent.id,
    name="Updated Demo Support Agent",
    description="An updated temporary demonstration Agent.",
)

endeavor.agents.delete(agent.id)
```

### Run a deployed Task

```python
result = endeavor.run(
    "demo-support-agent",
    "summarize-message",
    context={
        "message": "Summarize this example customer message.",
    },
)
```

Select an Environment and Version:

```python
result = endeavor.run(
    "demo-support-agent",
    "summarize-message",
    context={"message": "Summarize this text."},
    environment="production",
    version="1.2.3",
)
```

Use a complete deployed-task URL:

```python
result = endeavor.run(
    deployed_task_url=(
        "https://guidelight.dev/api/"
        "demo-support-agent/summarize-message"
    )
    context={"message": "Summarize this text."},
)
```

Run a deployed task with a file:

```python
with open("example.pdf", "rb") as document:
    result = endeavor.run(
        "demo-document-agent",
        "extract-document-text",
        context={"instruction": "Extract the important details."},
        files={
            "example.pdf": document,
        },
    )
```

`Endeavor.run()` returns `str` for `text/plain` responses and decoded Python
values for `application/json` responses.
