skrawcz commented on code in PR #644: URL: https://github.com/apache/burr/pull/644#discussion_r2749876764
########## .claude/skills/burr/patterns.md: ########## @@ -0,0 +1,668 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Apache Burr Design Patterns & Best Practices + +Architectural guidance and best practices for building production-ready Burr applications. + +## Core Design Principles + +### 1. Single Responsibility Actions + +Each action should do one thing well. + +**❌ Bad - Action does too much:** +```python +@action(reads=["query"], writes=["response", "documents", "reranked", "formatted"]) +def do_everything(state: State) -> State: + # Retrieves, reranks, generates, and formats all in one + docs = retrieve(state["query"]) + reranked = rerank(docs) + response = generate(reranked) + formatted = format(response) + return state.update( + documents=docs, + reranked=reranked, + response=response, + formatted=formatted + ) +``` + +**✅ Good - Focused actions:** +```python +@action(reads=["query"], writes=["documents"]) +def retrieve_documents(state: State) -> State: + docs = retrieve(state["query"]) + return state.update(documents=docs) + +@action(reads=["documents"], writes=["reranked"]) +def rerank_documents(state: State) -> State: + reranked = rerank(state["documents"]) + return state.update(reranked=reranked) + +# ... separate actions for generate and format +``` + +**Benefits:** +- Easier to test +- Easier to debug (can see which action failed) +- Reusable components +- Clear visualization in the Burr UI + +### 2. Accurate reads/writes Declarations + +Declare exactly what each action reads and writes. + +**❌ Bad:** +```python +@action(reads=[], writes=[]) # Inaccurate! +def process_user(state: State) -> State: + user_id = state["user_id"] # Actually reads user_id + profile = fetch_profile(user_id) + return state.update(profile=profile) # Actually writes profile +``` + +**✅ Good:** +```python +@action(reads=["user_id"], writes=["profile"]) +def process_user(state: State) -> State: + user_id = state["user_id"] + profile = fetch_profile(user_id) + return state.update(profile=profile) +``` + +**Benefits:** +- Self-documenting code +- Better debugging in UI +- Enables future optimizations +- Catches errors early + +### 3. State Immutability + +Never mutate state directly - always use `.update()` or `.append()`. Review Comment: slop ########## .claude/skills/burr/patterns.md: ########## @@ -0,0 +1,668 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Apache Burr Design Patterns & Best Practices + +Architectural guidance and best practices for building production-ready Burr applications. + +## Core Design Principles + +### 1. Single Responsibility Actions + +Each action should do one thing well. + +**❌ Bad - Action does too much:** +```python +@action(reads=["query"], writes=["response", "documents", "reranked", "formatted"]) +def do_everything(state: State) -> State: + # Retrieves, reranks, generates, and formats all in one + docs = retrieve(state["query"]) + reranked = rerank(docs) + response = generate(reranked) + formatted = format(response) + return state.update( + documents=docs, + reranked=reranked, + response=response, + formatted=formatted + ) +``` + +**✅ Good - Focused actions:** +```python +@action(reads=["query"], writes=["documents"]) +def retrieve_documents(state: State) -> State: + docs = retrieve(state["query"]) + return state.update(documents=docs) + +@action(reads=["documents"], writes=["reranked"]) +def rerank_documents(state: State) -> State: + reranked = rerank(state["documents"]) + return state.update(reranked=reranked) + +# ... separate actions for generate and format +``` + +**Benefits:** +- Easier to test +- Easier to debug (can see which action failed) +- Reusable components +- Clear visualization in the Burr UI + +### 2. Accurate reads/writes Declarations + +Declare exactly what each action reads and writes. + +**❌ Bad:** +```python +@action(reads=[], writes=[]) # Inaccurate! +def process_user(state: State) -> State: + user_id = state["user_id"] # Actually reads user_id + profile = fetch_profile(user_id) + return state.update(profile=profile) # Actually writes profile +``` + +**✅ Good:** +```python +@action(reads=["user_id"], writes=["profile"]) +def process_user(state: State) -> State: + user_id = state["user_id"] + profile = fetch_profile(user_id) + return state.update(profile=profile) +``` + +**Benefits:** +- Self-documenting code +- Better debugging in UI +- Enables future optimizations +- Catches errors early + +### 3. State Immutability + +Never mutate state directly - always use `.update()` or `.append()`. + +**❌ Bad:** +```python +@action(reads=["items"], writes=["items"]) +def add_item(state: State, item: str) -> State: + items = state["items"] + items.append(item) # Mutates state! + return state +``` + +**✅ Good:** +```python +@action(reads=["items"], writes=["items"]) +def add_item(state: State, item: str) -> State: + return state.append(items=item) +``` + +**Benefits:** +- Time-travel debugging +- State history for replay +- Prevents subtle bugs +- Enables state persistence + +### 4. Deterministic Actions + +Given the same state and inputs, an action should always produce the same output. + +**❌ Bad - Non-deterministic:** Review Comment: slop -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
