Skip to main content

Using in Python

Installation and Quickstart​

pip install llama-cloud-services
from llama_cloud_services import LlamaReport

# Initialize the client
client = LlamaReport(
    api_key="your-api-key",
    # Optional: Specify project_id, organization_id, async_httpx_client
)

# Create a new report
report = client.create_report(
    "My Report",
    # must have one of template_text or template_instructions
    template_text="Your template text",
    template_instructions="Instructions for the template",
    # must have one of input_files or retriever_id
    input_files=["data1.pdf", "data2.pdf"],
    retriever_id="retriever-id",
)

Working with Reports​

The typical workflow for a report involves:

  1. Creating the report
  2. Waiting for and approving the plan
  3. Waiting for report generation
  4. Making edits to the report

Here's a complete example:

# Create a report
report = client.create_report(
    "Quarterly Analysis", input_files=["q1_data.pdf", "q2_data.pdf"]
)

# Wait for the plan to be ready
plan = report.wait_for_plan()

# Option 1: Directly approve the plan
report.update_plan(action="approve")

# Option 2: Suggest and review edits to the plan
# This will automatically keep track of chat history locally (not remotely)
suggestions = report.suggest_edits(
    "Can you add a section about market trends?"
)
for suggestion in suggestions:
    print(suggestion)

    # Accept or reject the suggestion
    if input("Accept? (y/n): ").lower() == "y":
        report.accept_edit(suggestion)
    else:
        report.reject_edit(suggestion)

# Wait for the report to complete
report = report.wait_for_completion()

# Make edits to the final report
suggestions = report.suggest_edits("Make the executive summary more concise")

# Review and accept/reject suggestions as above
...

Getting the Final Report​

Once you are satisfied with the report, you can get the final report object and use the content as you see fit.

Here's an example of printing out the final report:

report = report.get()
report_text = "\n\n".join([block.template for block in report.blocks])

print(report_text)

Core Classes​

LlamaReport​

The main client class for managing reports and general report operations.

Constructor Parameters​

  • api_key (str, optional): Your LlamaCloud API key. Can also be set via LLAMA_CLOUD_API_KEY environment variable.
  • project_id (str, optional): Specific project ID to use.
  • organization_id (str, optional): Specific organization ID to use.
  • base_url (str, optional): Custom API base URL.
  • timeout (int, optional): Request timeout in seconds.
  • async_httpx_client (httpx.AsyncClient, optional): Custom async HTTP client.

Key Methods​

create_report​
def create_report(
    name: str,
    template_instructions: Optional[str] = None,
    template_text: Optional[str] = None,
    template_file: Optional[Union[str, tuple[str, bytes]]] = None,
    input_files: Optional[List[Union[str, tuple[str, bytes]]]] = None,
    existing_retriever_id: Optional[str] = None,
) -> ReportClient

Creates a new report. Must provide either template_instructions/template_text or template_file, and either input_files or existing_retriever_id.

This returns a ReportClient object, which you can use to work with the report.

list_reports​
def list_reports(
    state: Optional[str] = None,
    limit: int = 100,
    offset: int = 0
) -> List[ReportClient]

Lists all reports, with optional filtering by state. This returns a list of ReportClient objects.

get_report​
def get_report(report_id: str) -> ReportClient

Gets a ReportClient instance for working with a specific report.

get_report_metadata​
def get_report_metadata(report_id: str) -> ReportMetadata

Gets metadata for a specific report, including state and configuration details.

delete_report​
def delete_report(report_id: str) -> None

Deletes a specific report.

ReportClient​

Client for working with a specific report instance.

Key Methods​

get​
def get(self, version: Optional[int] = None) -> ReportResponse

Gets the full report content, optionally for a specific version.

get_metadata​
def get_metadata(self) -> ReportMetadata

Gets the current metadata for this report.

suggest_edits​
def suggest_edits(
    user_query: str,
    auto_history: bool = True,
    chat_history: Optional[List[dict]] = None,
) -> List[EditSuggestion]

Gets AI suggestions for edits based on your query.

By default, the auto_history flag is set to True, which means the SDK will automatically keep track of the chat history for each suggestion. This means that if you call suggest_edits multiple times, the SDK will automatically append the chat history to the previous chat history.

You can override this behavior by setting auto_history to False and providing a chat_history list. This list should contain dictionaries with role and content keys, where role is either "user" or "assistant":

chat_history = [
    {"role": "user", "content": "Can you add a section about market trends?"},
    {"role": "assistant", "content": "Sure, I'll add a section about market trends."},
]
accept_edit​
def accept_edit(suggestion: EditSuggestion) -> None

Accepts and applies a suggested edit to the report. Saves the action taken to use as part of the chat history for future edits (if auto_history is set to True).

reject_edit​
def reject_edit(suggestion: EditSuggestion) -> None

Rejects a suggested edit. Saves the action taken to use as part of the chat history for future edits (if auto_history is set to True).

wait_for_plan​
def wait_for_plan(
    timeout: int = 600,
    poll_interval: int = 5
) -> ReportPlan

Waits for the report's plan to be ready for review.

update_plan​
def update_plan(
    action: Literal["approve", "reject", "edit"],
    updated_plan: Optional[dict] = None,
) -> ReportResponse

Updates the report's plan. Use "approve" to accept the plan, "reject" to decline it, or "edit" to modify it (requires updated_plan).

get_events​
def get_events(
    last_sequence: Optional[int] = None
) -> List[ReportEventItemEventData_Progress]

Gets the event history for the report, optionally starting from a specific sequence number.

wait_for_completion​
def wait_for_completion(
    timeout: int = 600,
    poll_interval: int = 5
) -> Report

Waits for the report to finish generating.

Response Types​

EditSuggestion​

Represents a suggested edit from the AI.

Properties:

ReportPlan​

Represents the planned structure of a report.

Properties:

  • blocks: List of ReportPlanBlock objects
  • metadata: Additional plan metadata

Report​

Represents a generated report.

Properties:

  • blocks: List of ReportBlock objects
  • id: Report identifier

ReportResponse​

The main response type returned by many report operations.

Properties:

  • report_id: ID of the report
  • name: Name of the report
  • status: Current status of the report
  • report: The Report object (if available)
  • plan: The ReportPlan object (if available)

ReportMetadata​

Contains metadata about a report.

Properties:

  • id: Report ID
  • name: Report name
  • state: Current report state
  • report_metadata: Additional metadata dictionary
  • template_file: Name of template file if used
  • template_instructions: Template instructions if provided
  • input_files: List of input file names

ReportEventItemEventData_Progress​

Represents a progress event in the report generation process.

Properties:

  • msg: Event message
  • group_id: Group ID for putting events into common groups
  • timestamp: Event timestamp
  • status: The current status of the event operation

ReportBlock​

Represents a single block of content in a report.

Properties:

  • idx: Block index
  • template: Block content
  • sources: List of source references for the content

ReportPlanBlock​

Represents a planned block in the report structure.

Properties:

  • block: A ReportBlock object
  • metadata: Additional block metadata

Async Support​

All methods have async counterparts prefixed with 'a':

  • create_report → acreate_report
  • suggest_edits → asuggest_edits
  • wait_for_plan → await_for_plan
  • etc.