logmind 0.1.0__tar.gz

logmind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 logmind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logmind-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Include all template files
+recursive-include src/logmind/templates *.template *.md
+
+# Exclude test files and cache
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

logmind-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: logmind
+Version: 0.1.0
+Summary: Decision logging for AI-assisted development - automatic tracking, git integration, and context for AI agents
+Author: logmind contributors
+License: MIT
+Project-URL: Homepage, https://github.com/thrillmot/logmind
+Project-URL: Documentation, https://github.com/thrillmot/logmind#readme
+Project-URL: Repository, https://github.com/thrillmot/logmind
+Project-URL: Bug Tracker, https://github.com/thrillmot/logmind/issues
+Project-URL: Changelog, https://github.com/thrillmot/logmind/blob/main/CHANGELOG.md
+Keywords: ai,decision-logging,documentation,development,llm,ai-agents,decision-tracking,git-integration,claude,gpt,copilot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Dynamic: license-file
+
+# logmind
+
+[![PyPI](https://img.shields.io/pypi/v/logmind.svg)](https://pypi.org/project/logmind/)
+[![Python versions](https://img.shields.io/pypi/pyversions/logmind.svg)](https://pypi.org/project/logmind/)
+[![CI](https://github.com/thrillmot/logmind/actions/workflows/test.yml/badge.svg)](https://github.com/thrillmot/logmind/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+AI decision logging for development projects — branch-aware by default.
+
+## Why logmind
+
+Codebases lose the *why* behind their code faster than the *what*. logmind
+captures architectural and implementation decisions as you make them,
+attaches them to the relevant git branch, and surfaces them to the next
+human or AI that works in the repo. One CLI command per decision; the
+package handles the docs, the branch routing, and the merge-time
+aggregation.
+
+**Key concept:** Install once, init anywhere, log everything. Feature
+branches get their own decision file; on PR merge a GitHub Action appends
+a one-line summary to `docs/decisions.md` linking the PR + the branch
+detail. AGENTS.md is the canonical agent-instruction file; per-tool files
+(CLAUDE.md, .cursorrules, ...) are 2-line stubs pointing to it.
+
+## Installation
+
+```bash
+# Using pipx (recommended)
+pipx install logmind
+
+# Using Homebrew (macOS/Linux)
+brew tap thrillmot/logmind
+brew install logmind
+
+# Using pip
+pip install logmind
+```
+
+## Quick Start
+
+```bash
+# If installed via pipx/brew, it's already available globally
+
+# Initialize in your project
+cd your-project
+logmind init
+
+# Log decisions - Python API
+from logmind import log
+log("Chose FastAPI over Flask",
+    reasoning="Need async/await for WebSocket handling")
+
+# Or use CLI
+logmind log "Use PostgreSQL for database" \
+  -r "Need ACID compliance" \
+  -a "MongoDB" -a "SQLite"
+
+# View and search decisions
+logmind show
+logmind search "postgres"
+
+# Log with a built-in template (pre-fills reasoning, alternatives, implications)
+logmind log --template database "Use PostgreSQL"
+logmind templates   # list all available templates
+
+# Analytics and stats
+logmind stats
+logmind stats --months 6
+
+# Aggregate decisions across multiple projects
+logmind aggregate ~/projects/api ~/projects/frontend
+logmind aggregate --summary ~/work/*/
+
+# Enforce decision logging with a pre-commit hook
+logmind install-hook          # installs .git/hooks/pre-commit
+logmind check-decisions       # run manually or in CI
+
+# Manage AI agents
+logmind agents list
+logmind agents add windsurf
+
+# View and modify configuration
+logmind config list
+logmind config get git.auto_push
+logmind config set git.auto_push false
+
+# Upgrade logmind
+logmind update
+
+# Auto-log with decorators
+from logmind import log_decision, log_choice
+
+@log_decision(
+    decision="Authenticate user with {method}",
+    reasoning="Security checkpoint"
+)
+def authenticate(method="oauth"):
+    # Your auth code
+    return True
+
+@log_choice(
+    choices={
+        "redis": "Use Redis for caching",
+        "memory": "Use in-memory caching",
+    }
+)
+def select_cache():
+    return "redis" if is_production() else "memory"
+```
+
+## Contributing / Development Setup
+
+Working on logmind itself? Set it up like any CLI tool:
+
+```bash
+# Clone the repo
+git clone https://github.com/thrillmot/logmind.git
+cd logmind
+
+# Install globally in editable mode (like npm, git, docker)
+pipx install -e .
+
+# Now just use it!
+logmind log "Add new feature" -r "Reasoning here"
+logmind show
+logmind search "keyword"
+
+# Run tests
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+**Why pipx?** logmind is a CLI tool, not a library. It should be globally available like `git` or `npm`.
+
+## Framework Integrations
+
+```python
+# LangChain — auto-log agent decisions (pip install logmind[langchain])
+from logmind.integrations import LangChainLogger
+
+chain = LLMChain(llm=llm, callbacks=[LangChainLogger()])
+
+# Custom framework — subclass BaseIntegration
+from logmind.integrations.base import BaseIntegration
+
+class MyLogger(BaseIntegration):
+    def on_decision(self, output):
+        self.log(f"Chose: {output}", reasoning="My framework decided")
+```
+
+See [docs/custom-integrations.md](docs/custom-integrations.md) for patterns, examples, and publishing guide.
+
+## Documentation
+
+- **[Plan & Architecture](docs/plan.md)** - Vision, approach, and technical details
+- **[AI Agent Files](docs/ai-agent-files.md)** - How logmind integrates with AI instruction files
+- **[Custom Integrations](docs/custom-integrations.md)** - Build integrations for any AI framework
+- **[First Decision Example](docs/first-decision-example.md)** - What the initial decision looks like
+- **Development Status** - All phases complete ✅
+
+## How It Works
+
+1. **Install** logmind as a package
+2. **Init** creates `docs/` folder and inserts instructions into `CLAUDE.md` (preserving existing content)
+3. **Log** a decision - appends, archives old ones (keeps 20 recent), regenerates tree, commits, and pushes
+4. **Context** AI agents read the 20 most recent decisions and current file structure
+
+## Why logmind?
+
+- **Simple:** Two markdown files (recent + archive), no database
+- **Focused:** Only 20 most recent decisions for relevant AI context
+- **Git-native:** Every decision is a commit, git history is your audit trail
+- **AI-friendly:** Recent decisions + file structure = complete context
+- **Automatic:** Commits and pushes on every log
+
+See [docs/plan.md](docs/plan.md) for complete architecture and roadmap.

logmind-0.1.0/README.md

@@ -0,0 +1,178 @@
+# logmind
+
+[![PyPI](https://img.shields.io/pypi/v/logmind.svg)](https://pypi.org/project/logmind/)
+[![Python versions](https://img.shields.io/pypi/pyversions/logmind.svg)](https://pypi.org/project/logmind/)
+[![CI](https://github.com/thrillmot/logmind/actions/workflows/test.yml/badge.svg)](https://github.com/thrillmot/logmind/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+AI decision logging for development projects — branch-aware by default.
+
+## Why logmind
+
+Codebases lose the *why* behind their code faster than the *what*. logmind
+captures architectural and implementation decisions as you make them,
+attaches them to the relevant git branch, and surfaces them to the next
+human or AI that works in the repo. One CLI command per decision; the
+package handles the docs, the branch routing, and the merge-time
+aggregation.
+
+**Key concept:** Install once, init anywhere, log everything. Feature
+branches get their own decision file; on PR merge a GitHub Action appends
+a one-line summary to `docs/decisions.md` linking the PR + the branch
+detail. AGENTS.md is the canonical agent-instruction file; per-tool files
+(CLAUDE.md, .cursorrules, ...) are 2-line stubs pointing to it.
+
+## Installation
+
+```bash
+# Using pipx (recommended)
+pipx install logmind
+
+# Using Homebrew (macOS/Linux)
+brew tap thrillmot/logmind
+brew install logmind
+
+# Using pip
+pip install logmind
+```
+
+## Quick Start
+
+```bash
+# If installed via pipx/brew, it's already available globally
+
+# Initialize in your project
+cd your-project
+logmind init
+
+# Log decisions - Python API
+from logmind import log
+log("Chose FastAPI over Flask",
+    reasoning="Need async/await for WebSocket handling")
+
+# Or use CLI
+logmind log "Use PostgreSQL for database" \
+  -r "Need ACID compliance" \
+  -a "MongoDB" -a "SQLite"
+
+# View and search decisions
+logmind show
+logmind search "postgres"
+
+# Log with a built-in template (pre-fills reasoning, alternatives, implications)
+logmind log --template database "Use PostgreSQL"
+logmind templates   # list all available templates
+
+# Analytics and stats
+logmind stats
+logmind stats --months 6
+
+# Aggregate decisions across multiple projects
+logmind aggregate ~/projects/api ~/projects/frontend
+logmind aggregate --summary ~/work/*/
+
+# Enforce decision logging with a pre-commit hook
+logmind install-hook          # installs .git/hooks/pre-commit
+logmind check-decisions       # run manually or in CI
+
+# Manage AI agents
+logmind agents list
+logmind agents add windsurf
+
+# View and modify configuration
+logmind config list
+logmind config get git.auto_push
+logmind config set git.auto_push false
+
+# Upgrade logmind
+logmind update
+
+# Auto-log with decorators
+from logmind import log_decision, log_choice
+
+@log_decision(
+    decision="Authenticate user with {method}",
+    reasoning="Security checkpoint"
+)
+def authenticate(method="oauth"):
+    # Your auth code
+    return True
+
+@log_choice(
+    choices={
+        "redis": "Use Redis for caching",
+        "memory": "Use in-memory caching",
+    }
+)
+def select_cache():
+    return "redis" if is_production() else "memory"
+```
+
+## Contributing / Development Setup
+
+Working on logmind itself? Set it up like any CLI tool:
+
+```bash
+# Clone the repo
+git clone https://github.com/thrillmot/logmind.git
+cd logmind
+
+# Install globally in editable mode (like npm, git, docker)
+pipx install -e .
+
+# Now just use it!
+logmind log "Add new feature" -r "Reasoning here"
+logmind show
+logmind search "keyword"
+
+# Run tests
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+**Why pipx?** logmind is a CLI tool, not a library. It should be globally available like `git` or `npm`.
+
+## Framework Integrations
+
+```python
+# LangChain — auto-log agent decisions (pip install logmind[langchain])
+from logmind.integrations import LangChainLogger
+
+chain = LLMChain(llm=llm, callbacks=[LangChainLogger()])
+
+# Custom framework — subclass BaseIntegration
+from logmind.integrations.base import BaseIntegration
+
+class MyLogger(BaseIntegration):
+    def on_decision(self, output):
+        self.log(f"Chose: {output}", reasoning="My framework decided")
+```
+
+See [docs/custom-integrations.md](docs/custom-integrations.md) for patterns, examples, and publishing guide.
+
+## Documentation
+
+- **[Plan & Architecture](docs/plan.md)** - Vision, approach, and technical details
+- **[AI Agent Files](docs/ai-agent-files.md)** - How logmind integrates with AI instruction files
+- **[Custom Integrations](docs/custom-integrations.md)** - Build integrations for any AI framework
+- **[First Decision Example](docs/first-decision-example.md)** - What the initial decision looks like
+- **Development Status** - All phases complete ✅
+
+## How It Works
+
+1. **Install** logmind as a package
+2. **Init** creates `docs/` folder and inserts instructions into `CLAUDE.md` (preserving existing content)
+3. **Log** a decision - appends, archives old ones (keeps 20 recent), regenerates tree, commits, and pushes
+4. **Context** AI agents read the 20 most recent decisions and current file structure
+
+## Why logmind?
+
+- **Simple:** Two markdown files (recent + archive), no database
+- **Focused:** Only 20 most recent decisions for relevant AI context
+- **Git-native:** Every decision is a commit, git history is your audit trail
+- **AI-friendly:** Recent decisions + file structure = complete context
+- **Automatic:** Commits and pushes on every log
+
+See [docs/plan.md](docs/plan.md) for complete architecture and roadmap.

logmind-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "logmind"
+version = "0.1.0"
+description = "Decision logging for AI-assisted development - automatic tracking, git integration, and context for AI agents"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "logmind contributors"}
+]
+keywords = [
+    "ai", "decision-logging", "documentation", "development",
+    "llm", "ai-agents", "decision-tracking", "git-integration",
+    "claude", "gpt", "copilot"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+dependencies = [
+    "click>=8.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.5.0",
+    "pre-commit>=3.5.0",
+    "build>=1.0.0",
+]
+langchain = [
+    "langchain-core>=0.1.0",
+]
+
+[project.scripts]
+logmind = "logmind.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/thrillmot/logmind"
+Documentation = "https://github.com/thrillmot/logmind#readme"
+Repository = "https://github.com/thrillmot/logmind"
+"Bug Tracker" = "https://github.com/thrillmot/logmind/issues"
+Changelog = "https://github.com/thrillmot/logmind/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+logmind = [
+    "templates/*.template",
+    "templates/*.md",
+    "templates/github/*.template",
+]
+
+[tool.black]
+line-length = 100
+target-version = ['py38']
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]  # line length handled by black
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]  # allow asserts
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

logmind-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

logmind-0.1.0/src/logmind/__init__.py

@@ -0,0 +1,8 @@
+"""logmind - AI decision logging system for development projects."""
+
+__version__ = "0.1.0"
+
+from logmind.core.logger import log
+from logmind.decorators import log_choice, log_decision
+
+__all__ = ["log", "log_decision", "log_choice"]

logmind-0.1.0/src/logmind/actions/__init__.py

@@ -0,0 +1,5 @@
+"""GitHub Action entry points shipped with logmind.
+
+These modules are designed to run inside CI (`python -m logmind.actions.<name>`)
+but are also importable so they can be unit-tested without a full CI harness.
+"""

logmind-0.1.0/src/logmind/actions/aggregate.py

@@ -0,0 +1,108 @@
+"""Aggregate per-branch decision logs into docs/decisions.md on PR merge.
+
+Designed to be invoked by ``.github/workflows/logmind-aggregate.yml`` after a
+pull request is merged. Reads the per-branch decisions file written by Phase 5
+and appends a single summary entry to the canonical decisions log so the
+default branch's history shows merged work alongside its detail link.
+
+Importable for unit testing; ``main()`` adapts environment variables for use
+with ``python -m logmind.actions.aggregate``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from logmind.core.logger import _sanitize_branch
+from logmind.core.parser import iter_decisions
+
+
+def aggregate(
+    branch: str,
+    pr_number: int,
+    pr_url: str,
+    docs_path: Path,
+    timestamp: Optional[datetime] = None,
+) -> Optional[Path]:
+    """
+    Append a merge-summary entry to ``docs/decisions.md``.
+
+    Returns the path to the updated file, or ``None`` if the per-branch file is
+    missing / empty (in which case there is nothing to summarise and the main
+    log is left untouched).
+    """
+    if timestamp is None:
+        timestamp = datetime.now()
+
+    sanitized = _sanitize_branch(branch)
+    branch_file = docs_path / "decisions-branches" / f"{sanitized}.md"
+    if not branch_file.exists():
+        return None
+
+    decision_count = sum(1 for _ in iter_decisions(branch_file))
+    if decision_count == 0:
+        return None
+
+    rel_link = f"decisions-branches/{sanitized}.md"
+    entry = (
+        f"## {timestamp.strftime('%Y-%m-%d %H:%M')} - "
+        f"Merged: {branch} (#{pr_number})\n"
+        "\n"
+        f"- **PR:** {pr_url}\n"
+        f"- **Decisions:** {decision_count} from this branch\n"
+        f"- **Detail:** [{rel_link}]({rel_link})\n"
+        "\n"
+        "---\n"
+    )
+
+    decisions_path = docs_path / "decisions.md"
+    existing = decisions_path.read_text(encoding="utf-8") if decisions_path.exists() else ""
+    decisions_path.write_text(existing + entry, encoding="utf-8")
+    return decisions_path
+
+
+def main() -> int:
+    """Entry point for ``python -m logmind.actions.aggregate``."""
+    branch = os.environ.get("BRANCH_NAME") or os.environ.get("GITHUB_HEAD_REF")
+    pr_number_str = os.environ.get("PR_NUMBER")
+    pr_url = os.environ.get("PR_URL")
+
+    if not branch or not pr_number_str or not pr_url:
+        print(
+            "logmind aggregate: BRANCH_NAME, PR_NUMBER, and PR_URL must be set",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        pr_number = int(pr_number_str)
+    except ValueError:
+        print(f"logmind aggregate: PR_NUMBER must be an integer, got {pr_number_str!r}",
+              file=sys.stderr)
+        return 2
+
+    docs_path = Path(os.environ.get("LOGMIND_DOCS", "docs"))
+    if not docs_path.is_absolute():
+        docs_path = Path.cwd() / docs_path
+
+    result = aggregate(
+        branch=branch,
+        pr_number=pr_number,
+        pr_url=pr_url,
+        docs_path=docs_path,
+    )
+
+    if result is None:
+        print(f"logmind aggregate: no per-branch decisions for {branch}; nothing to do.")
+        return 0
+
+    print(f"logmind aggregate: appended merge summary for {branch} to {result}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())