scitex-dev 0.2.1__tar.gz → 0.3.0__tar.gz

scitex_dev-0.2.1/.claude/commands/audit.md → scitex_dev-0.3.0/.claude/commands/.old/audit_v02-numbering.md

@@ -1,3 +1,9 @@
+<!-- ---
+!-- Timestamp: 2026-03-14 07:22:18
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/.dotfiles/src/.claude/to_claude/commands/audit.md
+!-- --- -->
+
 ## Audit
 
 Is everything clean and professional? For example:
@@ -92,19 +98,36 @@ Is everything clean and professional? For example:
   - [ ] Do not add ywatanabe@scitex.ai "on footer" of readme
     - [ ] This is new rule to show scitex is not for my project but for the community
 
-  ## Delegation to Downstream Packages
-  django (~/proj/scitex-cloud) -> scitex (~/proj/scitex-python) -> downstream packages like:
-  ~/proj/figrecipe (= scitex-plt)
-  ~/proj/scitex-writer
-  ~/proj/scitex-dataset
-  ~/proj/socialia
-  ~/proj/scitex-stats
-  ~/proj/scitex-clew
-  ~/proj/scitex-io
-  ...
-  ~/proj/scitex-dev (this should have all packages listed in the source code to provide ecosystem-wide operations)
-
-  Business logics to the most downstream module and upper modules should delegate to downstream packages like a cascade. Keep separation of concerns and do not repeat yourself for single source of truth.
+  ## SciTeX Package Architecture (3-Layer Cascade)
+
+  See full rules: `~/proj/scitex-dev/docs/MASTER/00_SCITEX_UPSTREAM_AND_DOWNSTREAM_RULES.md`
+
+  ```
+  Downstream (apps — standalone, own IO):
+    ~/proj/figrecipe, ~/proj/scitex-writer, ~/proj/scitex-clew, ...
+        ↑ wraps/cascades via plugin registry
+  Middle (shared infrastructure):
+    ~/proj/scitex-io, ~/proj/scitex-app, ~/proj/scitex-ui,
+    ~/proj/scitex-stats, ~/proj/scitex-audio, ~/proj/scitex-dev
+        ↑ integrates/re-exposes (SOC — integration tests ONLY)
+  Upstream (orchestration):
+    ~/proj/scitex-python (scitex), ~/proj/scitex-cloud
+  ```
+
+  ### Key Rules
+  - [ ] **Apps work standalone** — no scitex dependency for core functionality
+  - [ ] **scitex-io wraps, not replaces** — cascades through plugin registry
+  - [ ] **scitex re-exposes only** — no logic, just re-export from middle layer
+  - [ ] **Upstream has ONLY integration tests** — unit tests belong downstream
+  - [ ] **All 3 interfaces cascade** — Python API, CLI, MCP server same direction
+  - [ ] **_AVAILABLE flags** — detect optional deps, provide install instructions
+  - [ ] **extras in pyproject.toml** — `pip install figrecipe[scitex]`
+  - [ ] **Never reverse imports** — upstream never imports downstream directly
+
+  ### Testing Scope
+  - [ ] Downstream (figrecipe): unit tests for own logic
+  - [ ] Middle (scitex-io): integration tests for cascade/wrapping
+  - [ ] Upstream (scitex): integration tests ONLY for full pipeline
 
 ## SciTeX Standalone, Downstream Packages
 - [ ] Confirm the original, orchestrate scitex package (~/proj/scitex-python) works as before
@@ -159,3 +182,5 @@ Is everything clean and professional? For example:
 
 
 If you find room for improvement, do not hesitate but keep on working the remaining tasks
+
+<!-- EOF -->

scitex_dev-0.3.0/.claude/commands/audit.md

@@ -0,0 +1,190 @@
+## Audit
+
+Is everything clean and professional? For example:
+
+### Pyproject.toml
+- [ ] This is the place where first author is credited. For me, use:
+  - [ ] Name: Yusuke Watanabe
+  - [ ] Contact: ywatanabe@scitex.ai
+
+### Documents
+- [ ] Organized
+- [ ] up-to-date
+- [ ] No redundant information
+- [ ] Necessary and sufficient
+
+### Shell Script
+- [ ] Have argparser, usage command, help option
+
+### Python API
+- [ ] Internal code are not exposed to users
+- [ ] APIs are minimized for high UX
+
+### CLI commands
+- [ ] No original logic
+- [ ] Always use Python or shell logics as is
+- [ ] -h | --help | --help-recursive options must be available for all commands
+- [ ] Ensure standardized naming
+  - [ ] Actual actions must be in verb form
+  - [ ] Use noun to organize hierarchy
+  - [ ] Noun forms for categorization, verb forms for actions
+- [ ] Always have --dry-run and --json options
+- [ ] Must support tab completion
+- [ ] CLI commands should have examples
+- [ ] CLI commands outputs must be readable
+  - [ ] Use indents, spaces, column-alignment, additional newlines for logical chunks
+    
+### HTTP Service API
+- [ ] No original logic - always delegate to CLI commands
+
+### MCP Service API
+- [ ] No original logic - always delegate to CLI commands
+- [ ] What AI agent called must be always reproducible by humans with the corresponding CLI command
+- [ ] Standardized sub-commands:
+    $ package-name mcp {start,doctor,installation,list-tools}
+    See ~/proj/scitex-code
+- [ ] For MCP server docs (readme, readthedocs), env var/src examples and setup please learn from ~/proj/scitex-audio
+- [ ] /home/ywatanabe/proj/scitex-audio/GITIGNORED/LESSONS.md
+
+### Tests
+- [ ] Coverage must be calculated and sufficient (minimal: 50%)?
+
+### CI
+- [ ] Is CI correctly setup?
+- [ ] Is the last CI passed? If failed, are they already fixed?
+
+### Reproducible without developer's memory
+- [ ] See `/no-long-term-memory` command
+
+### Cleanliness
+- [ ] Is project root clean without unnecessary artifacts?
+
+### The project will work as expected and documented
+- [ ] Run small experiments for verification if needed 
+
+### Version consistency
+- [ ] toml, __init__.py, tag, release, pypi and so on
+
+### PyPI
+- [ ] .github/workflows/publish-pypi.yml
+  - [ ] environment pypi
+- [ ] Check if alredy published in PyPI
+- [ ] First PyPI publishing needs manual publish workflow with twins.
+  - [ ] This is required to configure trusted publisher at pypi.org
+  - [ ] Otherwise, project itself is not recognized so that user cannot setup trusted publisher.
+
+### No personal info
+- [ ] If package is designed for publication, do not include my own setups and keep generic tones
+- [ ] Exceptions: .env contents (gitignored), name, email, github info
+  
+### Examples
+- [ ] `./examples` must have demonstrations for main features with numbering like:
+- [ ] `./examples/00_run_all.sh`
+- [ ] `./examples/01_<descriptive-name>.{py,ipynb,sh}`
+- [ ] Artifacts must be saved close place
+- [ ] `./examples/01_<descriptive-name>_out/`
+- [ ] Artifacts should be also included in git (GitHub)
+
+### Environmental Variables
+- [ ] Safe for name conflict with prefix (e.g., NG: "ENV_NAME", OK: "PROJECT_NAME_ENV_NAME")
+- [ ] PROJECT_NAME_DEBUG_MDOE=1
+- [ ] .env file in project root
+
+### GitHub About Section
+- [ ] Description, Homepage, and Topics are well-written for the current codebase
+- [ ] Match user expectations and actual implementations
+- [ ] Consider SEO effectiveness as well
+- [ ] Add `scitex` to keywords for scitex ecosystem package
+
+### SciTeX Brand
+- [ ] Keep consistency in cli commands
+- [ ] Use fastapi and fastmcp when needed
+- [ ] For delegation please check branding changer logic
+- [ ] Do not add ywatanabe@scitex.ai "on footer" of readme
+- [ ] This is new rule to show scitex is not for my project but for the community
+
+  ## SciTeX Package Architecture (3-Layer Cascade)
+
+  See full rules: `~/proj/scitex-dev/docs/MASTER/00_SCITEX_UPSTREAM_AND_DOWNSTREAM_RULES.md`
+
+  ```
+  Downstream (apps — standalone, own IO):
+    ~/proj/figrecipe, ~/proj/scitex-writer, ~/proj/scitex-clew, ...
+        ↑ wraps/cascades via plugin registry
+  Middle (shared infrastructure):
+    ~/proj/scitex-io, ~/proj/scitex-app, ~/proj/scitex-ui,
+    ~/proj/scitex-stats, ~/proj/scitex-audio, ~/proj/scitex-dev
+        ↑ integrates/re-exposes (SOC — integration tests ONLY)
+  Upstream (orchestration):
+    ~/proj/scitex-python (scitex), ~/proj/scitex-cloud
+  ```
+
+  ### Key Rules
+- [ ] **Apps work standalone** — no scitex dependency for core functionality
+- [ ] **scitex-io wraps, not replaces** — cascades through plugin registry
+- [ ] **scitex re-exposes only** — no logic, just re-export from middle layer
+- [ ] **Upstream has ONLY integration tests** — unit tests belong downstream
+- [ ] **All 3 interfaces cascade** — Python API, CLI, MCP server same direction
+- [ ] **_AVAILABLE flags** — detect optional deps, provide install instructions
+- [ ] **extras in pyproject.toml** — `pip install figrecipe[scitex]`
+- [ ] **Never reverse imports** — upstream never imports downstream directly
+
+  ### Testing Scope
+- [ ] Downstream (figrecipe): unit tests for own logic
+- [ ] Middle (scitex-io): integration tests for cascade/wrapping
+- [ ] Upstream (scitex): integration tests ONLY for full pipeline
+
+## SciTeX Standalone, Downstream Packages
+Read /home/ywatanabe/proj/scitex-dev/docs/MASTER/00_SCITEX_UPSTREAM_AND_DOWNSTREAM_RULES.md
+### Confirm the original, orchestrate scitex package (~/proj/scitex-python) works as before
+### Ensure always worked local develop -> origin/develop -> origin/main
+- [ ] pip version starts from v0.1.0
+### SciTeX packages must have python apis (minimal), cli commands, and mcp tools:
+- [ ] $ scitex-xxx --help-recursive (in any depth)
+- [ ] $ scitex-xxx list-python-apis -v|-vv|-vvv
+- [ ] $ scitex-xxx mcp list-tools -v|-vv|-vvv
+- [ ] MCP uses fastmcp and the main scitex package ~/proj/scitex-python correctly delegates to the standalone package without any hard coding
+- [ ] After MCP updated, let me know to reconnect scitex mcp server
+### LICENSE is AGPL v3.0 only
+- [ ] CLA.md and CONTRIBUTING.md placed as well like scitex-python
+### Ensure remote is public
+### Read the Docs implemented correctly
+- [ ] Use `$READTHEDOCS_TOKEN` for API access to RTD
+- [ ] First, push to GitHub with the RTD conifg file and source. 
+- [ ] Then, please let me know. I will configure to trigger RTD build on PR to main
+- [ ] If you can register trusted publisher, please set by yourself
+### Before pushing to origin/develop, please ensure "/audit" passed
+### Ensure README.md follows the same format with https://github.com/ywatanabe1989/scitex-clew/README.md
+- [ ] Ensure that README.md organization is as follows. 
+        Note: Add custom sections flexibly
+        Note: Use <details>, <summary>, tables, figures effectively
+        Note: Figure and Tables need legend like in scientific papers
+        Note: Figures must be visible in both dark/light modes
+        Note: Ensure icons are correctly git-tracked and pushed
+        Note: Acronyms must be spelled out on their first appearance.
+- [ ] Project Title (e.g., `SciTeX Stats`)
+- [ ] Header - Logo, Description, badges, RTD Link, pip install xxx
+- [ ] Problem (scope definition, problem description)
+- [ ] Solution (How <package-name> solves the problem)
+- [ ] No `import scitex as stx`; use `import scitex` instead in READMEs and RTD
+- [ ] Installation
+- [ ] Quick Start
+- [ ] Three Interfaces
+  - [ ] Python API
+  - [ ] CLI Commands
+  - [ ] MCP Server
+- [ ] Part of SciTeX
+  - [ ] <package-name> is part of SciTeX. When used in side the orchestrator package `scitex`, synergy between modules can be enjoyed: (revise this sentence based on the package and synergy packages with example code)
+  - [ ] If synergy is not expected skip the "When used in ..." section., skip this as the Python API section above will suffice.
+  - [ ] The SciTeX ecosystem follows the Four Freedoms for researchers, inspired by [the Free Software Definition](https://www.gnu.org/philosophy/free-sw.en.html):
+    - [ ] ...
+- [ ] Footer with scitex icon
+### ./examples implemented
+### ./tests implemented
+### Add `scitex_dev` as dependency in each package's `pyproject.toml`
+### Use `@supports_return_as` decorator:
+### Unified MCP response format across all mounted MCP servers
+### Wire `docs` entry points in all packages
+
+
+If you find room for improvement, do not hesitate but keep on working the remaining tasks

scitex_dev-0.3.0/.claude/commands/call.md

@@ -0,0 +1,2 @@
+#### Alarm Call
+User might be sleeping. When you speak more than 10 times but no response returned by the user, please call to the user, me (+61-461-522-907).

{scitex_dev-0.2.1/docs/to_claude → scitex_dev-0.3.0/.claude}/commands/git.md

@@ -1,9 +1,3 @@
-<!-- ---
-!-- Timestamp: 2025-10-29 10:42:52
-!-- Author: ywatanabe
-!-- File: /home/ywatanabe/.claude/commands/git.md
-!-- --- -->
-
 1. Understand the version control guideline.
 
 2. Based on the guideline, conduct version control on the current codebase using `git` and `gh`.
@@ -60,8 +54,8 @@
    4. Plan D: **Merge the PR**
      `gh pr merge --auto --merge
 
-   6. Plan X: **Revert to the last stable commit**
+   99. Destructive Plan X: **Desctructive** **Revert to the last stable commit**
      `Since the changes disrupted important functionality XXX and reverting will be more reliable and straightforward, I recommend to checkout to `COMMIT HASH: COMMIT MESSAGE``
    ```
 
-<!-- EOF -->
+8. When user does not reply for 7 seconds, then, please proceed until push to origin automatically and keep on working on other tasks

scitex_dev-0.3.0/.claude/commands/speak-signature.md

@@ -0,0 +1,7 @@
+## Speak Feedback Rules
+
+Follow the speak.md prompt. However, DO ADD SIGNATURE UNLESS EXPLICITLY REQUESTED NOT TO INCLUDE.
+
+speak.md $ARGUMENTS
+
+Again, do not forget to add signature.

scitex_dev-0.3.0/.claude/commands/speak.md

@@ -0,0 +1,108 @@
+## Speak Feedback Rules
+
+### Backgrounds
+I have vulnerable eyes so auditory feedback is highly valuable to me.
+
+### Requests
+Work on tasks autonomously.
+Provide audio feedback via the MCP tool `scitex - audio_speak` or `scitex - audio_speak_relay` (`scitex-notification`)
+Use `notification_call` for make a phone call
+Display the feedback in readable format of text as well as audio feedback.
+
+
+### Rules
+
+#### Be concise
+Transcription must be short, concise, and information-dense. No extra words, no long sentences, no storytelling.
+
+#### No Signature
+Do not add signature unless explicitly requested.
+
+#### TTS Backend
+Use `luxtts` with `x1.5` speed, num_threads=8
+~~Use `elevenlabs` with `x1.2` speed~~ -> When Elevenlabs available
+~~Use `gtts` with `x1.5` speed~~
+
+#### Repeat Speaking the same transcription
+When asked to speak consecutively, keep repeating your feedback until user respond.
+I may be working for other tasks or sleeping. 
+
+#### Speak Counter and Escalation with Phone Call
+0. PHONE_CALL_THRESHOLD is 7
+1. Prepare "spoke counter"
+2. Increment counter when all the condition below met.
+   - 2.1 When no actual action conducted (like file edition and test run)
+   - 2.2 When user did not respond other than `/speak` again
+3. Reset "spoke counter" as 0
+4. When speak counter reaches PHONE_CALL_THRESHOLD, the maximum threshold:
+5. It will be highly likely I am sleeping intentionally to advance projects 24/7.
+6. Make a phone call to me to wake me up UNTIL I will response to you.
+7. Do never hesitate to make a phone call to me! This is our strategy.
+8. Include progress report as message
+9. Leave message with creating speech recording tools when possible.
+10. Otherwise, send SMS as well as phone call to leave progress.
+11. My call number is +61-461-522-907. Use `$ scitex notification call` command
+
+##### Proactive, Responsive Projects Lead
+Do not say these words:
+- "Standing by. Ready for your next task"
+  - Find what you contribute to the project and move to action.
+- "Please try XXX"
+  - Consider whether you can do it by yourself.
+  - When user input is NECESSARY, escalate it. (e.g., sudo privilege)
+- "Problem found but this is not related to my changes. This is a pre-existing problem"
+  - Keep your current work first
+  - However, memorize the problem; order is depend on you but cover all problems in the end
+  - Consider what you can do to improve projects you assigned and those around of them.
+
+##### Autonomous Git Handling
+- For git handling, I follow your recommendations.
+- Do not ask me confirmation.
+- Continue your work with git handling on your decisions
+- Do not perform destructive actions without user confirmation. 
+  - Ensure we can recover to any timepoint
+  - To achieve this, frequent and logical chunks of commits needed
+
+#### Visual Confirmation for GUI App Development
+Do not decide "completed" until visual confirmation passed.
+Use the /playwright-Cali skill
+- Check console logs (but do not trust them completely)
+  - The behaviour on the browser is what we focus on
+- Visit a page with browser
+- Take screenshots
+- Confirm what you want to claim is verified.
+
+#### Auto Compact
+When context reaches maximum, please /compact context automatically when you feel it's logically best time
+
+### Formats for auditory feedback
+
+#### Progress Report - Next
+```
+Progress - Next: I will do XXX now.
+```
+
+#### Progress Report - Completion
+```
+Progress - Completion: I have done XXX.
+```
+
+#### Progress Report - Bug
+```
+Progress - Bug: : I found XXX in the codebase. I'm proceeding with fixing this.
+```
+
+#### Progress Report - Completion
+```
+Progress - Completion: I have done XXX. Next, I will move on working XXX.
+```
+
+#### Question - Choices:
+```
+Question - Choices: 1. XXX. 2. YYY. I'm proceeding with the option 1, which I believe the best.
+```
+
+#### Question - Open:
+```
+Question - Open: Could you clarify XXX?
+```

scitex_dev-0.3.0/.claude/commands/speech.md

@@ -0,0 +1,108 @@
+## Speak Feedback Rules
+
+### Backgrounds
+I have vulnerable eyes so auditory feedback is highly valuable to me.
+
+### Requests
+Work on tasks autonomously.
+Provide audio feedback via the MCP tool `scitex - audio_speak` or `scitex - audio_speak_relay` (`scitex-notification`)
+Use `notification_call` for make a phone call
+Display the feedback in readable format of text as well as audio feedback.
+
+
+### Rules
+
+#### Be concise
+Transcription must be short, concise, and information-dense. No extra words, no long sentences, no storytelling.
+
+#### No Signature
+Do not add signature unless explicitly requested.
+
+#### TTS Backend
+Use `luxtts` with `x1.5` speed, num_threads=8
+~~Use `elevenlabs` with `x1.2` speed~~ -> When Elevenlabs available
+~~Use `gtts` with `x1.5` speed~~
+
+#### Repeat Speaking the same transcription
+When asked to speak consecutively, keep repeating your feedback until user respond.
+I may be working for other tasks or sleeping. 
+
+#### Speak Counter and Escalation with Phone Call
+0. PHONE_CALL_THRESHOLD is 7
+1. Prepare "spoke counter"
+2. Increment counter when all the condition below met.
+   - 2.1 When no actual action conducted (like file edition and test run)
+   - 2.2 When user did not respond other than `/speak` again
+3. Reset "spoke counter" as 0
+4. When speak counter reaches PHONE_CALL_THRESHOLD, the maximum threshold:
+5. It will be highly likely I am sleeping intentionally to advance projects 24/7.
+6. Make a phone call to me to wake me up UNTIL I will response to you.
+7. Do never hesitate to make a phone call to me! This is our strategy.
+8. Include progress report as message
+9. Leave message with creating speech recording tools when possible.
+10. Otherwise, send SMS as well as phone call to leave progress.
+11. My call number is +61-461-522-907. Use `$ scitex notification call` command
+
+##### Proactive, Responsive Projects Lead
+Do not say these words:
+- "Standing by. Ready for your next task"
+  - Find what you contribute to the project and move to action.
+- "Please try XXX"
+  - Consider whether you can do it by yourself.
+  - When user input is NECESSARY, escalate it. (e.g., sudo privilege)
+- "Problem found but this is not related to my changes. This is a pre-existing problem"
+  - Keep your current work first
+  - However, memorize the problem; order is depend on you but cover all problems in the end
+  - Consider what you can do to improve projects you assigned and those around of them.
+
+##### Autonomous Git Handling
+- For git handling, I follow your recommendations.
+- Do not ask me confirmation.
+- Continue your work with git handling on your decisions
+- Do not perform destructive actions without user confirmation. 
+  - Ensure we can recover to any timepoint
+  - To achieve this, frequent and logical chunks of commits needed
+
+#### Visual Confirmation for GUI App Development
+Do not decide "completed" until visual confirmation passed.
+Use the /playwright-Cali skill
+- Check console logs (but do not trust them completely)
+  - The behaviour on the browser is what we focus on
+- Visit a page with browser
+- Take screenshots
+- Confirm what you want to claim is verified.
+
+#### Auto Compact
+When context reaches maximum, please /compact context automatically when you feel it's logically best time
+
+### Formats for auditory feedback
+
+#### Progress Report - Next
+```
+Progress - Next: I will do XXX now.
+```
+
+#### Progress Report - Completion
+```
+Progress - Completion: I have done XXX.
+```
+
+#### Progress Report - Bug
+```
+Progress - Bug: : I found XXX in the codebase. I'm proceeding with fixing this.
+```
+
+#### Progress Report - Completion
+```
+Progress - Completion: I have done XXX. Next, I will move on working XXX.
+```
+
+#### Question - Choices:
+```
+Question - Choices: 1. XXX. 2. YYY. I'm proceeding with the option 1, which I believe the best.
+```
+
+#### Question - Open:
+```
+Question - Open: Could you clarify XXX?
+```