clawmind 0.1.1__tar.gz

clawmind-0.1.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: clawmind
+Version: 0.1.1
+Summary: Task-state-machine-first runner for Logseq-driven workflows.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: flashtext>=2.7
+
+# ClawMind -- Logseq AI Coworker
+
+> From chat to interaction.
+> You’re not talking to AI—you’re thinking with yourself.
+
+ClawMind is a Logseq-native workflow runner for individuals who need AI execution with human
+  oversight.
+  It turns everyday notes, questions, and task blocks into
+  a controlled execution flow that is understandable,
+  replayable, and auditable.
+
+  Unlike a generic AI chat tool, ClawMind separates flow
+  control, reasoning, and writeback into explicit system
+  boundaries.
+  Work Runner manages task intake and state transitions,
+  Codex Runner handles reasoning-heavy execution, and the
+  Deterministic Executor writes results back in a
+  repeatable way.
+
+## Why ClawMind
+
+  ClawMind is designed for knowledge workflows where
+  correctness, traceability, and operational clarity
+  matter.
+
+- Logseq remains the human-facing workflow surface.
+- AI execution is bounded by explicit runtime and
+  writeback rules.
+- Every run can leave reproducible audit evidence in
+  `run_logs/` and `runtime_artifacts/`.
+- The system is built to reduce ad hoc task handling and
+  turn repeated thinking work into durable process assets.
+
+## Demo
+
+<video src="./logseq_Edemo.mp4" controls></video>
+
+## How It Works
+
+  ClawMind turns a Logseq task into a controlled workflow:
+
+  `DOING -> WAITING -> execute -> writeback -> audit`
+
+```mermaid
+sequenceDiagram
+    participant L as Logseq Task
+    participant W as Work Runner
+    participant C as Codex Runner
+    participant D as Deterministic Executor
+
+    L->>W: DOING task detected
+    W->>W: Normalize id and lock as WAITING
+    W->>C: Build context and execute
+    C-->>W: Return structured result
+    W->>D: Apply deterministic writeback
+    D-->>L: Update answer and links
+    W-->>L: Record audit trail
+```
+
+### Roles
+
+  - Work Runner is the flow controller.
+    It scans DOING tasks, normalizes id::, moves tasks
+    into WAITING, builds execution context, and
+    coordinates the full run.
+  - Codex Runner is the reasoning engine.
+    It handles the AI-heavy part of the task and returns
+    structured output, but it does not directly mutate
+    Logseq pages or task state.
+  - Deterministic Executor is the writeback layer.
+    It applies results in a repeatable way, writes answer
+    pages and journal links, and helps preserve
+    idempotency and auditability.
+
+## Core Guarantees
+
+- stable `id::` primary key
+- runtime / knowledge domain separation
+- writeback idempotency
+- AI does not write to Logseq directly
+
+## Project Structure
+
+```text
+app/                Core application code
+tests/              Unit tests
+run_logs/           Execution audit records
+runtime_artifacts/  Execution artifacts
+```
+
+## Environment Requirements
+
+- WINDOWS OS
+- Install Codex CLI (Plus / month)
+- Install Logseq
+- Python 3.13+
+
+## Configuration
+
+The program resolves configuration files in this order:
+
+1. The file specified by `CLAWMIND_ENV_PATH`
+2. `.env` in the current working directory
+3. `.env` in the project root
+
+Common settings:
+
+```env
+LOGSEQ_PATH=<your Logseq root directory>
+CODEX_CLI_PATH=<path to the codex executable>
+JOURNAL_SCAN_DAYS=<optional>
+MAX_RETRIES=<optional>
+CODEX_TIMEOUT_SECONDS=<optional>
+```
+
+Variable notes
+
+- JOURNAL_SCAN_DAYS
+  - Unset = scan all journals
+  - Set = scan only the most recent N days
+- MAX_RETRIES defaults to 2
+- CODEX_TIMEOUT_SECONDS defaults to 300 seconds
+- Example CODEX_CLI_PATH: `C:\Users\<Username>\AppData\Local\nvm\v24.11.0\codex.cmd`
+
+## Installation
+
+Development environment:
+
+```powershell
+uv sync
+```
+
+To install as a CLI:
+
+```powershell
+pip install -e .
+```
+
+If you are not using `uv`, use:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+## Run
+
+**Persistent worker**
+
+```powershell
+clawmind run-worker
+```
+
+**Stop**
+
+```
+Ctrl+C
+```
+
+On startup, the program prints `config_source` and `env_path` so you can verify which configuration source was actually used.
+
+## CLI Helper Commands
+
+Check version:
+
+```powershell
+clawmind version
+```
+
+Show installation info:
+
+```powershell
+clawmind install-info
+```
+
+Upgrade:
+
+```powershell
+clawmind upgrade --method auto
+clawmind upgrade --method pipx
+clawmind upgrade --method uv
+clawmind upgrade --method pip
+```
+
+Method mapping:
+
+- `pipx install clawmind` -> `clawmind upgrade --method pipx`
+- `uv tool install clawmind` -> `clawmind upgrade --method uv`
+- `pip install clawmind` -> `clawmind upgrade --method pip`
+
+## Roadmap
+
+- Support macOS.
+- Support Gemini CLI and Claude CLI.
+- 
+
+## Contact
+
+- X.com @pigslybear

clawmind-0.1.1/README.md

@@ -0,0 +1,200 @@
+# ClawMind -- Logseq AI Coworker
+
+> From chat to interaction.
+> You’re not talking to AI—you’re thinking with yourself.
+
+ClawMind is a Logseq-native workflow runner for individuals who need AI execution with human
+  oversight.
+  It turns everyday notes, questions, and task blocks into
+  a controlled execution flow that is understandable,
+  replayable, and auditable.
+
+  Unlike a generic AI chat tool, ClawMind separates flow
+  control, reasoning, and writeback into explicit system
+  boundaries.
+  Work Runner manages task intake and state transitions,
+  Codex Runner handles reasoning-heavy execution, and the
+  Deterministic Executor writes results back in a
+  repeatable way.
+
+## Why ClawMind
+
+  ClawMind is designed for knowledge workflows where
+  correctness, traceability, and operational clarity
+  matter.
+
+- Logseq remains the human-facing workflow surface.
+- AI execution is bounded by explicit runtime and
+  writeback rules.
+- Every run can leave reproducible audit evidence in
+  `run_logs/` and `runtime_artifacts/`.
+- The system is built to reduce ad hoc task handling and
+  turn repeated thinking work into durable process assets.
+
+## Demo
+
+<video src="./logseq_Edemo.mp4" controls></video>
+
+## How It Works
+
+  ClawMind turns a Logseq task into a controlled workflow:
+
+  `DOING -> WAITING -> execute -> writeback -> audit`
+
+```mermaid
+sequenceDiagram
+    participant L as Logseq Task
+    participant W as Work Runner
+    participant C as Codex Runner
+    participant D as Deterministic Executor
+
+    L->>W: DOING task detected
+    W->>W: Normalize id and lock as WAITING
+    W->>C: Build context and execute
+    C-->>W: Return structured result
+    W->>D: Apply deterministic writeback
+    D-->>L: Update answer and links
+    W-->>L: Record audit trail
+```
+
+### Roles
+
+  - Work Runner is the flow controller.
+    It scans DOING tasks, normalizes id::, moves tasks
+    into WAITING, builds execution context, and
+    coordinates the full run.
+  - Codex Runner is the reasoning engine.
+    It handles the AI-heavy part of the task and returns
+    structured output, but it does not directly mutate
+    Logseq pages or task state.
+  - Deterministic Executor is the writeback layer.
+    It applies results in a repeatable way, writes answer
+    pages and journal links, and helps preserve
+    idempotency and auditability.
+
+## Core Guarantees
+
+- stable `id::` primary key
+- runtime / knowledge domain separation
+- writeback idempotency
+- AI does not write to Logseq directly
+
+## Project Structure
+
+```text
+app/                Core application code
+tests/              Unit tests
+run_logs/           Execution audit records
+runtime_artifacts/  Execution artifacts
+```
+
+## Environment Requirements
+
+- WINDOWS OS
+- Install Codex CLI (Plus / month)
+- Install Logseq
+- Python 3.13+
+
+## Configuration
+
+The program resolves configuration files in this order:
+
+1. The file specified by `CLAWMIND_ENV_PATH`
+2. `.env` in the current working directory
+3. `.env` in the project root
+
+Common settings:
+
+```env
+LOGSEQ_PATH=<your Logseq root directory>
+CODEX_CLI_PATH=<path to the codex executable>
+JOURNAL_SCAN_DAYS=<optional>
+MAX_RETRIES=<optional>
+CODEX_TIMEOUT_SECONDS=<optional>
+```
+
+Variable notes
+
+- JOURNAL_SCAN_DAYS
+  - Unset = scan all journals
+  - Set = scan only the most recent N days
+- MAX_RETRIES defaults to 2
+- CODEX_TIMEOUT_SECONDS defaults to 300 seconds
+- Example CODEX_CLI_PATH: `C:\Users\<Username>\AppData\Local\nvm\v24.11.0\codex.cmd`
+
+## Installation
+
+Development environment:
+
+```powershell
+uv sync
+```
+
+To install as a CLI:
+
+```powershell
+pip install -e .
+```
+
+If you are not using `uv`, use:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e .
+```
+
+## Run
+
+**Persistent worker**
+
+```powershell
+clawmind run-worker
+```
+
+**Stop**
+
+```
+Ctrl+C
+```
+
+On startup, the program prints `config_source` and `env_path` so you can verify which configuration source was actually used.
+
+## CLI Helper Commands
+
+Check version:
+
+```powershell
+clawmind version
+```
+
+Show installation info:
+
+```powershell
+clawmind install-info
+```
+
+Upgrade:
+
+```powershell
+clawmind upgrade --method auto
+clawmind upgrade --method pipx
+clawmind upgrade --method uv
+clawmind upgrade --method pip
+```
+
+Method mapping:
+
+- `pipx install clawmind` -> `clawmind upgrade --method pipx`
+- `uv tool install clawmind` -> `clawmind upgrade --method uv`
+- `pip install clawmind` -> `clawmind upgrade --method pip`
+
+## Roadmap
+
+- Support macOS.
+- Support Gemini CLI and Claude CLI.
+- 
+
+## Contact
+
+- X.com @pigslybear

clawmind-0.1.1/app/__init__.py

@@ -0,0 +1 @@
+"""ClawMind application package."""

clawmind-0.1.1/app/adapters/__init__.py

@@ -0,0 +1 @@
+"""External adapters package."""

clawmind-0.1.1/app/adapters/filesystem_adapter.py

@@ -0,0 +1 @@
+"""Filesystem adapter placeholder for future implementation."""