@stephen-lord/docs 1.0.0

package/dist/agent-skills/openai-skills/spreadsheets/examples/create_basic_spreadsheet.py

@@ -0,0 +1,102 @@
+"""Example: create a new spreadsheet, add a sheet, set cells, read ranges."""
+
+# ruff: noqa: I001
+from __future__ import annotations
+from pprint import pprint
+
+from artifact_tool import SpreadsheetArtifact
+
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+)
+
+
+def main() -> None:
+    # Create a new spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("AwesomeCompany")
+
+    # Look at what exists
+    spreadsheet.get_sheet("Overview")  # None
+
+    overviews_sheet = spreadsheet.create_sheet("Overview")
+    employees_sheet = spreadsheet.create_sheet("Employees")
+
+    overviews_sheet.cell("A1").value = "Description"
+    overviews_sheet.cell("A2").value = "Awesome Company Report"
+
+    # Write headers with the range helper
+    employees_sheet.range("A1:D1").set_values([["Title", "Name", "Address", "Score"]])  # row 1
+    employees_sheet.range("A2:D4").set_values(
+        [
+            ["Engineer", "Vicky", "90 50th Street", 98],  # row 2
+            ["Manager", "Alex", "500 Market Street", 92],  # row 3
+            ["Designer", "Jordan", "200 Pine Street", 88],  # row 4
+        ]
+    )
+
+    print("\nCreating a basic spreadsheet template with the following structure:")
+    pprint(spreadsheet.to_dict())
+
+    print("Adding a total scores row with a sum formula")
+
+    # Skip a line and add a sum formula cell
+    employees_sheet.cell("A6").set_value("Total Score")
+    employees_sheet.cell("D6").formula = "=SUM(D2:D4)"
+    assert employees_sheet.formula("D6") == "=SUM(D2:D4)"
+    assert employees_sheet.cell("D6").data == "=SUM(D2:D4)"
+
+    employees_sheet.recalculate()
+    assert employees_sheet.cell("D6").value == 278
+    assert employees_sheet.cell("D6").data == "=SUM(D2:D4)"
+
+    # Edit with the bracket shortcut
+    print("Updating Vicky's title to Standing Desk Operator")
+    employees_sheet.cell("A2").value = "Standing Desk Operator"
+
+    print("Updating Alex's name to Alex V2 and address to [private] address")
+    employees_sheet.range("B3:C3").values = [["Alex V2", "[private] address"]]
+
+    # Add a new column for promotions
+    print("Adding a new column for promotions")
+    employees_sheet.range("E1:E4").set_values([["Promotion"], [True], [False], [True]])
+
+    # Make sure vicky is getting a promption
+    assert employees_sheet.value("E2") is True
+    assert employees_sheet.cell("E2").value is True
+
+    # Read what you made
+    print("\n==Overview sheet (raw data):")
+    pprint(overviews_sheet.range("A1:E4").get_data())
+
+    print("\n==Scores sheet (raw data):")
+    pprint(employees_sheet.range("A1:E6").get_data())
+
+    print("\n==Scores sheet (values):")
+    pprint(employees_sheet.range("A1:E6").values)
+
+    print("\n==Scores sheet as a dictionary:")
+    pprint(employees_sheet.to_dict())
+
+    print("\n==Serialized workbook dictionary:")
+    pprint(spreadsheet.to_dict())
+
+    print("\n==Serialized workbook length:")
+    pprint(len(spreadsheet.to_json()))
+
+    # Render the final spreadsheet
+    render_path = spreadsheet.render()
+    print(f"Rendered spreadsheet to {render_path}")
+
+    # Saves it to binary format in the current directory
+    proto_path = spreadsheet.save()
+    print(f"Saved spreadsheet proto to {proto_path}")
+
+    export_path = spreadsheet.export()
+    print(f"Exported spreadsheet to {export_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/create_spreadsheet_with_styling.py

@@ -0,0 +1,199 @@
+"""Generate a styled games scoreboard spreadsheet artifact.
+
+This script demonstrates how to assemble a multi-sheet `SpreadsheetArtifact`
+similar to ``sample_jsons/GamesSimpleStyling.json`` using the higher-level API.
+Run it to emit the workbook JSON to stdout or pass ``--output`` to write it to disk.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from pprint import pprint
+
+from oaiproto.coworker.pptx.utils_pb2 import Color, Fill, TextStyle
+from oaiproto.coworker.xlsx.spreadsheet_pb2 import CfRule, DifferentialFormat
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+from artifact_tool.spreadsheet.conditional_formatting import CfType, len_greater_than_zero_formula
+
+HEADER_FILL_HEX = "FFB7E1CD"
+HIGHLIGHT_FILL_HEX = "FFFFF2CC"
+
+"""
+This creates a simple spreadsheet with two sheets, one for Game X and one for Game Y.
+With a simple header style row and players filled in.
+
+It demonstrates how to create styles and apply them to cells.
+It demonstrates how to create conditional formatting, merge cells, etc.
+
+Example:
+`python examples/spreadsheets/create_spreadsheet_with_styling.py --output ~/tmp/styled_xlsx.xlsx --format xlsx --render`
+"""
+
+
+def solid_fill(color_hex: str) -> Fill:
+    """Return a solid fill proto for the given RGB hex color."""
+
+    normalized = color_hex.lstrip("#").upper()
+    return Fill(type="FILL_TYPE_SOLID", color=Color(type="COLOR_TYPE_RGB", value=normalized))
+
+
+def create_styles(artifact: SpreadsheetArtifact) -> dict[str, int]:
+    """Register reusable styles on the workbook and return their indices."""
+
+    # Header style: bold font, pastel fill, centered alignment.
+    text_style = TextStyle(name="Aptos Narrow", family=2, scheme="minor", font_size=11, bold=True)
+    header_cell_style_index = artifact.create_cell_format(
+        text_style=text_style,
+        fill=solid_fill(HEADER_FILL_HEX),
+        horizontal_alignment="center",
+        vertical_alignment="center",
+    )
+
+    # Highlight style reused for winner callouts.
+    highlight_cell_style_index = artifact.create_cell_format(
+        fill=solid_fill(HIGHLIGHT_FILL_HEX),
+        text_style=text_style,
+        horizontal_alignment="center",
+        vertical_alignment="center",
+    )
+
+    return {
+        "header": header_cell_style_index,
+        "highlight": highlight_cell_style_index,
+    }
+
+
+def populate_first_game_sheet(artifact: SpreadsheetArtifact, style_indices: dict[str, int]) -> None:
+    """Create the "GameX" sheet with scores and a summary row."""
+
+    sheet = artifact.sheet("GameX")
+    sheet.set_sheet_styles(default_row_height=15.75)
+    sheet.set_row_height(2, 35.25)
+
+    sheet.set_column_widths("C", 13.1640625)
+    sheet.set_column_widths("D", 13.5)
+    sheet.set_column_widths("E", 11.1640625)
+    sheet.set_column_widths("F", 40)
+
+    headers_range = sheet.range("A2:G2")
+    headers_range.set_values(
+        [["", "Name", "Game 1 Score", "Game 2 Score", "Total Score", "Notes", ""]]
+    )
+    headers_range.set_style_index(style_indices["header"])
+
+    name_score_range = sheet.range("B3:D5")
+    name_score_range.set_values(
+        [
+            ["Vicky", 12, 30],
+            ["Yash", 20, 10],
+            ["Bobby", 1000, 1030],
+        ]
+    )
+
+    # Set the total score formula column
+    total_score_range = sheet.range("E3:E5")
+    total_score_range.set_formulas([["=SUM(C3:D3)"], ["=SUM(C4:D4)"], ["=SUM(C5:D5)"]])
+
+    notes_column = sheet.range("F3:F5")
+    notes_column.set_values(
+        [
+            ["Dominated the minigames."],
+            ["Emily main with strong defense."],
+            ["Numbers look suspiciously high."],
+        ]
+    )
+
+    # Actually, reset F5
+    sheet.cell("F5").value = "Rematch penciled in for Friday."
+
+    # Now, fill in a last row for the summary row - 7th row
+
+    sheet.cell("B7").value = "Winner"
+    sheet.cell("C7").formula = "=INDEX(B4:B6, MATCH(MAX(E4:E6), E4:E6, 0))"
+    sheet.cell("E7").value = "Congrats!"
+    sheet.range("B7:E7").set_style_index(style_indices["highlight"])
+
+    # Let's merge C7 and D7
+    sheet.range("C7:D7").merge()
+
+    sheet.create_conditional_formatting(
+        ranges=["A2:G2"],
+        rules=[
+            CfRule(
+                type=CfType.NOT_CONTAINS_BLANKS,
+                formula=[len_greater_than_zero_formula("A2")],
+            )
+        ],
+        style=DifferentialFormat(fill=solid_fill(HEADER_FILL_HEX)),
+    )
+
+
+def build_workbook() -> SpreadsheetArtifact:
+    """Create the scoreboard workbook with both sheets populated."""
+
+    artifact = SpreadsheetArtifact("GamesSimpleStyling")
+    style_indices = create_styles(artifact)
+
+    populate_first_game_sheet(artifact, style_indices)
+
+    return artifact
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate the GamesSimpleStyling workbook JSON")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help=("Optional destination file. Leave unset to print the workbook to_dict() to stdout."),
+    )
+    parser.add_argument(
+        "--format",
+        choices=["json", "bin", "xlsx"],
+        default="json",
+        help="Output type to use when saving the workbook.",
+    )
+    parser.add_argument(
+        "--render",
+        action="store_true",
+        default=False,
+        help="Render the workbook to PNG images.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    artifact = build_workbook()
+    output_format = args.format
+
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        if output_format == "json":
+            file_type = FileOutputType.C_STAR_PROTO_JSON
+        elif output_format == "bin":
+            file_type = FileOutputType.C_STAR_PROTO_BINARY
+        elif output_format == "xlsx":
+            file_type = FileOutputType.XLSX
+        else:
+            raise ValueError(f"Invalid output type: {output_format}")
+
+        path = artifact.save(
+            file_type=file_type,
+            filename=args.output,
+            overwrite=True,
+        )
+        print("Saving workbook to", path)
+    else:
+        workbook_dict = artifact.to_dict()
+        print("Workbook created successfully: to_dict()")
+        pprint(workbook_dict)
+
+    if args.render:
+        render_paths = artifact.render()
+        print("Rendered workbook to", render_paths)
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/change_existing_charts.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from artifact_tool import SpreadsheetArtifact
+
+
+def main() -> None:
+    file_path = Path(__file__).resolve().parent / ".." / "sample_xlsx" / "weather_sf.xlsx"
+    spreadsheet = SpreadsheetArtifact.read(file_path=file_path)
+
+    dashboard = spreadsheet.sheet("Dashboard")
+
+    print(f"Charts before deletion: {len(dashboard.charts)}")
+    for i, chart in enumerate(dashboard.charts):
+        print(f"Chart {i}: {chart.title}")
+
+    del dashboard.charts[0]
+
+    print(f"Charts after deletion: {len(dashboard.charts)}")
+    for i, chart in enumerate(dashboard.charts):
+        print(f"Chart {i}: {chart.title}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/cite_cells.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from artifact_tool import SpreadsheetArtifact
+
+
+def main() -> None:
+    spreadsheet = SpreadsheetArtifact("CiteDemo")
+    first_sheet = spreadsheet.sheet("Sheet1")
+
+    # Example data.
+    first_sheet.range("A1:C3").set_values(
+        [
+            ["Note", "hello", "hello"],
+            ["a", "b", "c"],
+            ["d", "e", "f"],
+        ]
+    )
+    # Add note on the range (anchors to top-left A1 by default).
+    first_sheet.range("A1:C3").cite(
+        tether_id="123456789",
+        start_line_number=12,
+        end_line_number=18,
+    )
+
+    first_sheet.cell("A4").set_value("This is a note on the cell A4.")
+    first_sheet.cell("A4").cite(tether_id="1234567890", start_line_number=23, end_line_number=46)
+
+    # Inspect proto->dict verification.
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "cite_cells"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+    # as_dict = spreadsheet.to_dict()
+    # print(as_dict)
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/create_area_chart.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from oaiproto.coworker.pptx.chart_pb2 import Chart
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    game_sheet = spreadsheet.sheet("MyFavoriteGame")
+
+    # Seed some data
+    game_sheet["A1:C1"].values = [["Player", "Game 1", "Game 2"]]
+    game_sheet["A2:C5"].values = [
+        ["Vicky", 120, 100],
+        ["Yash", 134, 95],
+        ["Dibyo", 95, 110],
+        ["Bobby", 105, 105],
+    ]
+
+    # Set up some ranges to use as labels (categories) and values for the charts
+    labels = game_sheet.range("A2:A5")
+    game1 = game_sheet.range("B2:B5")
+    game2 = game_sheet.range("C2:C5")
+
+    # Add an area chart to the cell range E2:I14
+    chart1 = game_sheet.charts.add(
+        game_sheet.range("E2:I14"),
+        Chart.ChartType.CHART_TYPE_AREA,
+        title="Game Scores",
+    )
+    chart1.add_series("Game 1", categories_range=labels, values_range=game1)
+    chart1.add_series("Game 2", categories_range=labels, values_range=game2)
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "create_area_chart"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/create_bar_chart.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from oaiproto.coworker.pptx.chart_pb2 import BarDirection, BarGrouping, Chart
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+from artifact_tool.models.charts import BarChart
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    game_sheet = spreadsheet.sheet("MyFavoriteGame")
+
+    # Seed some data
+    game_sheet["A1:C1"].values = [["Player", "Game 1", "Game 2"]]
+    game_sheet["A2:C5"].values = [
+        ["Vicky", 120, 100],
+        ["Emily", 134, 95],
+        ["Dibyo", 95, 110],
+        ["Bobby", 105, 105],
+    ]
+
+    # Set up some ranges to use as labels (categories) and values for the charts
+    labels = game_sheet.range("A2:A5")
+    game1 = game_sheet.range("B2:B5")
+    game2 = game_sheet.range("C2:C5")
+
+    # Add a vertical bar chart to the cell range E2:I14
+    chart1 = game_sheet.charts.add(
+        game_sheet.range("E2:I14"),
+        Chart.ChartType.CHART_TYPE_BAR,
+        title="Game Scores",
+    )
+    chart1.add_series("Game 1", categories_range=labels, values_range=game1)
+    chart1.add_series("Game 2", categories_range=labels, values_range=game2)
+
+    # Add a horizontal bar chart to the cell range E17:I29
+    chart2 = game_sheet.charts.add(
+        game_sheet.range("E17:I29"),
+        Chart.ChartType.CHART_TYPE_BAR,
+        title="Total Scores",
+    )
+    assert isinstance(chart2, BarChart)
+    chart2.bar_direction = BarDirection.BAR_DIRECTION_BAR
+    chart2.bar_grouping = BarGrouping.BAR_GROUPING_STACKED
+    chart2.add_series("Game 1", categories_range=labels, values_range=game1)
+    chart2.add_series("Game 2", categories_range=labels, values_range=game2)
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "create_bar_chart"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/create_doughnut_chart.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from oaiproto.coworker.pptx.chart_pb2 import Chart, LegendPosition
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    first_game_sheet = spreadsheet.sheet("Game1")
+
+    # Seed some data
+    first_game_sheet["A1:C1"].values = [["Player", "Game 1", "Game 2"]]
+    first_game_sheet["A2:C5"].values = [
+        ["Vicky", 120, 100],
+        ["Emily", 134, 95],
+        ["Dibyo", 95, 110],
+        ["Bobby", 105, 105],
+    ]
+
+    # Set up some ranges to use as labels (categories) and values for the charts
+    labels = first_game_sheet.range("A2:A5")
+    game1 = first_game_sheet.range("B2:B5")
+
+    # Add a doughnut chart to the cell range E2:I14
+    chart1 = first_game_sheet.charts.add(
+        first_game_sheet.range("E2:I14"),
+        Chart.ChartType.CHART_TYPE_DOUGHNUT,
+        title="Game Scores",
+    )
+    chart1.add_series("Game 1", categories_range=labels, values_range=game1)
+
+    # Show the legend and position it to the right
+    chart1.legend.visible = True
+    chart1.legend.position = LegendPosition.LEGEND_POSITION_RIGHT
+
+    output_dir = (
+        Path(__file__).resolve().parent / "golden_rendered_images" / "create_doughnut_chart"
+    )
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/create_line_chart.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from oaiproto.coworker.pptx.chart_pb2 import Chart
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    first_sheet = spreadsheet.sheet("GameX")
+
+    # Seed some data
+    first_sheet["A1:C1"].values = [["Player", "Game 1", "Game 2"]]
+    first_sheet["A2:C5"].values = [
+        ["Vicky", 120, 100],
+        ["Emily", 134, 95],
+        ["Dibyo", 95, 110],
+        ["Bobby", 105, 105],
+    ]
+
+    # Set up some ranges to use as labels (categories) and values for the charts
+    labels = first_sheet.range("A2:A5")
+    game1 = first_sheet.range("B2:B5")
+    game2 = first_sheet.range("C2:C5")
+
+    # Add a line chart to the cell range E2:I14
+    chart1 = first_sheet.charts.add(
+        first_sheet.range("E2:I14"),
+        Chart.ChartType.CHART_TYPE_LINE,
+        title="Game Scores",
+    )
+    chart1.add_series("Game 1", categories_range=labels, values_range=game1)
+    chart1.add_series("Game 2", categories_range=labels, values_range=game2)
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "create_line_chart"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

package/dist/agent-skills/openai-skills/spreadsheets/examples/features/create_pie_chart.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from oaiproto.coworker.pptx.chart_pb2 import Chart, LegendPosition
+
+from artifact_tool import FileOutputType, SpreadsheetArtifact
+
+
+def main() -> None:
+    # New spreadsheet artifact
+    spreadsheet = SpreadsheetArtifact("Scores")
+    first_sheet = spreadsheet.sheet("GameX")
+
+    # Seed some data
+    first_sheet["A1:C1"].values = [["Player", "Game 1", "Game 2"]]
+    first_sheet["A2:C5"].values = [
+        ["Vicky", 120, 100],
+        ["Emily", 134, 95],
+        ["Dibyo", 95, 110],
+        ["Bobby", 105, 105],
+    ]
+
+    # Set up some ranges to use as labels (categories) and values for the charts
+    labels = first_sheet.range("A2:A5")
+    game1 = first_sheet.range("B2:B5")
+
+    # Add a pie chart to the cell range E2:I14
+    chart1 = first_sheet.charts.add(
+        first_sheet.range("E2:I14"),
+        Chart.ChartType.CHART_TYPE_PIE,
+        title="Game Scores",
+    )
+    chart1.add_series("Game 1", categories_range=labels, values_range=game1)
+
+    # Show the legend and position it to the right
+    chart1.legend.visible = True
+    chart1.legend.position = LegendPosition.LEGEND_POSITION_RIGHT
+
+    output_dir = Path(__file__).resolve().parent / "golden_rendered_images" / "create_pie_chart"
+    output_path = spreadsheet.render(output=output_dir)
+    print(f"Spreadsheet rendered to {output_path}")
+
+    spreadsheet.save(
+        file_type=FileOutputType.C_STAR_PROTO_JSON,
+        filename=output_dir / "workbook__auto.json",
+        overwrite=True,
+    )
+
+    # output_path = spreadsheet.export()
+    # print(f"Spreadsheet exported to {output_path}")
+
+
+if __name__ == "__main__":
+    main()