Guidelight

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

Getting Started

Install Guidelight:

pip install guidelight

Configure an Endeavor API key:

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:

import guidelight as gdl

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

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

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

The high-level SDK also exposes its authenticated client:

client = endeavor.client

Low-level Client

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

GET

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

POST

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

PUT

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:

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

DELETE

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

Execute a deployed Task

Execute by Agent and Task slug or ID:

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

Select a deployed Release by Environment and semantic Version:

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.

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:

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

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:

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

Create, update, and delete an Agent

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

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

Select an Environment and Version:

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:

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:

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.