Updated README(s) with API Compatibility Instructions

[MinuraPunchihewa]

This PR updates the README with instructions for how to use the new version of the SDK with the refactored Minds API. A separate README is also maintained for users of the legacy API.

Fixes https://linear.app/mindsdb/issue/STRC-187/document-older-python-sdk-version-compatible-with-writer-legacy-api

[entelligence-ai-pr-reviews]

🔒 Entelligence AI Vulnerability Scanner

✅ No security vulnerabilities found!

Your code passed our comprehensive security analysis.

📊 Files Analyzed: 7 files

---

[entelligence-ai-pr-reviews]

Review Summary

🏷️ Draft Comments (11)

Skipped posting 11 draft comments that were valid but scored below your review threshold (>=13/15). Feel free to update them here.

examples/base_usage.py (2)

50-61: wait_for_mind function reassigns mind inside the loop, but this does not update the original mind object outside the function, leading to possible use of stale status after waiting.

📊 Impact Scores:

• Production Impact: 3/5
• Fix Specificity: 3/5
• Urgency Impact: 2/5
• Total Score: 8/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In examples/base_usage.py, lines 50-61, the function `wait_for_mind` reassigns `mind` inside the function, but this does not update the original object outside the function, which can lead to using a stale `mind` after waiting. Please update the function so that it returns the latest `mind` object after waiting, and update all calls to `wait_for_mind` to use the returned value.

---

50-62: The wait_for_mind function uses a polling loop with a fixed 3-second sleep, which can cause unnecessary delays and resource waste, especially if many minds are created in parallel or if the status is checked too frequently.

📊 Impact Scores:

• Production Impact: 2/5
• Fix Specificity: 4/5
• Urgency Impact: 2/5
• Total Score: 8/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In examples/base_usage.py, lines 50-62, the `wait_for_mind` function uses a fixed 3-second polling interval, which can cause unnecessary delays and resource waste, especially at scale. Refactor this function to use an exponential backoff polling strategy (starting at 1s, doubling up to 10s), and add a max_wait timeout (e.g., 5 minutes). Ensure the function raises a TimeoutError if the mind is not ready in time, and preserve the original print and error handling logic.

---

minds/client.py (1)

16-16: self.knowledge_bases is commented out, so any code expecting Client.knowledge_bases will fail with AttributeError at runtime.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 5/5
• Urgency Impact: 3/5
• Total Score: 12/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/client.py, line 16, the assignment to self.knowledge_bases is commented out. This will cause AttributeError if any code tries to access client.knowledge_bases. Uncomment this line so that self.knowledge_bases is properly initialized.

---

minds/datasources/datasources.py (1)

111-114: The list method uses a manual loop to build ds_list, which is less efficient and less readable than a list comprehension for large datasets.

📊 Impact Scores:

• Production Impact: 2/5
• Fix Specificity: 5/5
• Urgency Impact: 1/5
• Total Score: 8/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/datasources/datasources.py, lines 111-114, replace the manual loop that builds ds_list with a list comprehension for better performance and readability. Change:
ds_list = []
for item in data:
    ds_list.append(Datasource(**item))
return ds_list
to:
return [Datasource(**item) for item in data]

---

minds/minds.py (3)

23-24: parameters and datasources default to mutable objects ({} and []), causing shared state across instances and potential data corruption.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 5/5
• Urgency Impact: 3/5
• Total Score: 12/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/minds.py, lines 23-24, the Mind class __init__ method uses mutable default arguments for `datasources` and `parameters`, which can cause shared state and data corruption. Change the defaults to `None` for both arguments, and update the constructor logic to set them to empty list/dict if None is provided.

---

61-61: In add_datasource, using self.datasources + [{'name': datasource_name, 'tables': tables}] will fail if self.datasources is None, causing a TypeError at runtime.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 5/5
• Urgency Impact: 3/5
• Total Score: 12/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/minds.py, line 61, the code in add_datasource assumes self.datasources is always a list, but it can be None, causing a TypeError. Change the line to use (self.datasources or []) to ensure it always concatenates lists.

---

171-172: Inefficient list construction in Minds.list: using a loop with append instead of a list comprehension causes unnecessary interpreter overhead for large datasets.

📊 Impact Scores:

• Production Impact: 2/5
• Fix Specificity: 5/5
• Urgency Impact: 1/5
• Total Score: 8/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/minds.py, lines 171-172, replace the explicit for-loop that appends to `minds_list` with a list comprehension for better performance and readability. Change:

minds_list = []
for item in data:
    minds_list.append(Mind(self.client, **item))

to:

minds_list = [Mind(self.client, **item) for item in data]

---

minds/rest_api.py (3)

43-78: Default argument data={} in delete, post, put, and patch methods causes shared mutable state, leading to unexpected data leakage between calls.

📊 Impact Scores:

• Production Impact: 3/5
• Fix Specificity: 5/5
• Urgency Impact: 2/5
• Total Score: 10/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/rest_api.py, lines 43-78, the methods `delete`, `post`, `put`, and `patch` use a mutable default argument `data={}`. This can cause data leakage between calls. Change the default to `data=None` and add `if data is None: data = {}` at the start of each method to prevent shared state.

---

38-80: requests calls in get, delete, post, put, and patch methods lack a timeout, risking indefinite blocking and resource exhaustion under network issues or server hangs.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 5/5
• Urgency Impact: 3/5
• Total Score: 12/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/rest_api.py, lines 38-80, all HTTP requests (`requests.get`, `requests.delete`, `requests.post`, `requests.put`, `requests.patch`) are missing a `timeout` parameter. This can cause the application to hang indefinitely if the server does not respond, leading to resource exhaustion and degraded user experience. Add a reasonable timeout (e.g., `timeout=10`) to each of these requests to ensure the client does not block forever.

---

37-81: url parameter in all HTTP methods (get, post, put, patch, delete) is concatenated directly to base_url without validation or sanitization, enabling path traversal or SSRF if attacker controls url.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 3/5
• Urgency Impact: 4/5
• Total Score: 11/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/rest_api.py, lines 37-81, the `url` parameter in all HTTP methods is concatenated directly to `base_url` without validation, allowing path traversal or SSRF if attacker controls `url`. Add validation to ensure `url` is a safe, relative path (starts with '/', contains no scheme, netloc, or '..'). Apply this check before making the request in each method.

---

minds/utils.py (1)

30-51: validate_datasource_name claims to return bool, but never returns True on valid input, violating its contract and causing callers to receive None instead of True.

📊 Impact Scores:

• Production Impact: 4/5
• Fix Specificity: 5/5
• Urgency Impact: 3/5
• Total Score: 12/15

🤖 AI Agent Prompt (Copy & Paste Ready):

In minds/utils.py, lines 30-51, the function `validate_datasource_name` claims to return a bool but does not return `True` on valid input, violating its contract. Add `return True` at the end of the function so that it returns `True` when the input is valid.

---

🔍 Comments beyond diff scope (1)

minds/utils.py (1)

6-28: validate_mind_name and validate_datasource_name claim to return bool, but they never return True on valid input, violating their contract and causing callers to receive None instead of True.
Category: correctness

---

[ZoranPandovski]

Looks good. One minor note is that maybe it is better to keep the legacy readme as README-legacy and latest as just a README, so it is shown by default in the repo