Hello, dear friend, you can consult us at any time if you have any questions, add WeChat: daixieit

ICS 33 — Assignment 5 - Mini-Project:

Guild Inventory Explorer

Deadline: Sep 3rd, 11:59 PM

Theme: Game world inventory (recursive dungeon trees)

Estimated workload: ~10–15 hours

Changelog

● Thursday, August 28, 2025

○ In the Grading section, removed cohesion and docstrings from the Design portion of the grade.

○ Removed part about pytest

Learning Objectives

● (Option) Recursively or iteratively traverse hierarchical structures.

● Apply functional programming (map, filter, reduce) idioms.

● Use decorators to log and validate query behavior.

● Design with Abstract Base Classes (ABCs) for extensibility.

● Practice binary search over a sorted view of data.

Generative AI Extra Credit

Use of gen AI: You may use generative AI (gen AI) to help you (e.g., ChatGPT or Copilot), but you must include (1) all prompts and outputs provided by the gen AI and (2) any modifications you made to the resulting outputs provided and why you modified the outputs as such. This policy allows us to understand (1) how you are using gen AI and (2) help you use it more effectively, so as to demonstrate to others (e.g., future or possible employers) that you are adding value beyond the gen AI itself (e.g., you are worth hiring as a junior developer rather than having a senior developer just use the gen AI and not hire a junior developer). To encourage the submission of such gen AI-oriented materials, submitting this information in a file called genai_io.pdf will earn you up to 3 points of extra credit. We will grade that file on the quality of your prompts, the sensibility of the modifications to outputs, and the reasoning behind those modifications. Note that code generated using the current state-of-the-art generative AI has a strong tendency to be overly verbose and hallucinate, so we will be checking for such properties and others when evaluating quality and sensibility. Avoid just prompting and re-prompting generative AI without understanding the output. We will discuss strategies to assist you with this as we progress through the lectures.

We will also be using tools to detect your use of generative AI, so if we have strong suspicions that you have used generative AI without following the policy specified above, you may face a severe penalty, including failing the assignment or having your incident reported to the UCI Office of Academic Integrity & Student Conduct (OAISC), which may lead to suspension or dismissal/expulsion.

Scenario

Your guild maintains a hierarchical inventory across World → Region → Dungeon → Room → Chest. Each chest holds items.

You’ll build a Guild Inventory Explorer that:

1. (Option) Recursively or iteratively traverses the tree and yields items.

a. You can use depth-first search (DFS) or any other tree traversal algorithm that appropriately solves the problem at hand.

2. Filters, maps, and reduces items in functional style.

3. Finds items by sku using binary search (after sorting by sku).

4. Applies decorators for logging and predicate validation.

5. Loads the tree from JSON via an InventorySource ABC.

Data Format (JSON)

Minimal schema example:

JSON

{

"world": "Azeron",

"regions": [

{

"name": "Frostvale",

"dungeons": [

{

"name": "Grimhold",

"rooms": [

{

"name": "Antechamber",

"chests": [

{

"name": "Iron Chest #1",

"items": [

{"sku": "7F-ICE-BOW", "name": "Ice Bow",

"rarity": "epic",

"qty": 1, "base_price": 420.0, "tags":

["bow","ice","ranged"]}

]

}

]

}

]

}

]

}

],

"version": 1

}

Requirements

Models

● Item dataclass: sku, name, rarity, qty, base_price, tags.

Abstract Base Class

● InventorySource (ABC):

○ root() -> Any — returns the root of the world tree.

○ version() -> int | str — monotonic version for invalidating caches, if used.

● JSONInventorySource: loads from JSON.

Query Engine (minimum API)

● walk_items() → recursively yield all Items.

● filter_items(pred) → yield items where pred(item) is True.

● map_items(fn) → yield the result of applying fn(item).

● reduce_items(reducer, initial) → fold items with reducer(acc, item).

● find_item_by_sku(sku) → flatten items, sort by sku, perform binary search, return the Item or None.

Decorators

● @logged_query — prints the function name and count of items returned.

● @validate_predicate — ensures the predicate (used in filter_items) returns

bool; otherwise raises QueryValidationError.

● Subcommands:

○ list — list all items, optionally filtered by rarity.

○ find — find an item by SKU using the engine’s binary search.

○ value — compute total value (qty * base_price), optionally filtered by rarity.

● The CLI must call the engine methods (do not re-implement traversal/search inside CLI).

● Output formatting should remain stable and consistent for grading.

Write-Up

design_and_complexity.md (~1 page) addressing:

● Your tree traversal complexity.

● How decorators improve modularity and safety.

Suggested Milestones (6 steps + buffer)

● Day 1–2: JSONInventorySource → load JSON, materialize tree.

● Day 3: Recursive or iterative tree traversal (walk_items).

● Day 4: filter_items and map_items.

● Day 5: reduce_items (aggregations).

● Day 6: find_item_by_sku (sort + binary search).

● Day 7: Add decorators.

● Day 8–10: Tests, short write-up, buffer for the final exam.

Grading (100 pts)

● Correctness (autograder/public+hidden tests): 70

● Design (ABCs, types): 10

● Decorators (logging + validation): 10

● Write-up quality/clarity: 5

● Optional CLI (if added): 5

CLI Usage

Shell

python guild.py data/sample_small.json list --rarity epic

python guild.py data/sample_small.json find --sku 7F-ICE-BOW

python guild.py data/sample_small.json value --rarity rare

Submission

● Submit your code files (models.py, errors.py, abc_sources.py, decorators.py, engine.py, cli.py) as part of your project.

● Include your write-up file (design_and_complexity.md).

● Ensure your code runs correctly with the provided sample JSON and passes the test suite.