pylumen 1.0.1

The official CLI for the Lumen Protocol & Local Prompt Generation.

The official CLI for the Lumen Protocol & Local Prompt Generation.

---

Table of Contents

• Why Lumen?
• Features
• Prerequisites
• Installation & Troubleshooting
• Commands
  • Network Commands
  • Local Prompt Generation
  • Configuration
• Documentation
• Contributing
• License

---

Why Lumen?

Lumen started as a powerful local tool for developers to generate flawless, LLM-ready prompts from their codebases, solving the tedious process of manual context building. As we built it, we recognized a larger opportunity: the very code developers were analyzing held immense, untapped value for the AI ecosystem.

This led to the expansion of our vision. Lumen is now a dual-purpose CLI:

1. A Best-in-Class Local Prompt Helper: It remains a top-tier, 100% private utility for your daily AI-assisted development.
2. A Gateway to the Data Economy: It serves as a secure bridge to the Lumen Protocol, allowing developers to ethically contribute their anonymized code and earn rewards for helping build the next generation of AI.

Whether you use it locally or to interact with the network, you're using a tool built by developers, for developers. If you find the local tools useful, please consider starring the repository!

Features

• Network Interaction: Securely contribute your anonymized code to the Lumen Protocol and track your submission history.
• Local Prompt Generation: Assemble entire codebases into a single, LLM-ready prompt without sending any data.
• 100% Local Anonymization: All code sanitization for protocol contributions happens on your machine. Your raw code is never uploaded.
• Smart File Handling: Intelligently respects .gitignore, parses Jupyter Notebooks (.ipynb), and uses an optimized file reading strategy.
• GitHub Repository Support: Analyze any public GitHub repository directly by providing its URL.
• Token Usage Analysis: Identify the most token-heavy files in a project to help manage context window limitations.
• Customizable Filtering: Edit a simple config.json file to control which files, folders, and types are processed.

Prerequisites

1. Python (3.7 or higher): Check with python --version. Ensure Python is added to your system's PATH during installation.
2. Git: Required only for analyzing GitHub repositories (-g flag). Check with git --version.

Installation & Troubleshooting

Install directly from PyPI:

pip install pylumen

To upgrade to the latest version:

pip install --upgrade pylumen

Troubleshooting command not found: lum

This common issue occurs when the directory where pip installs scripts is not in your system's PATH.

• Quick Fix: Run the tool as a Python module: python -m lum --version. If this works, you can use python -m lum instead of lum.
• Permanent Fix (Recommended):
  • macOS/Linux: Find your Python script path (often ~/.local/bin) and add it to your shell configuration file (~/.zshrc, ~/.bashrc, or ~/.bash_profile) by adding this line: export PATH="$HOME/.local/bin:$PATH". Restart your terminal or run source ~/.zshrc (or your respective file).
  • Windows: The easiest way is to reinstall Python and ensure the "Add Python to PATH" checkbox is selected during the installation process.

Commands

Network Commands

These commands interact with the Lumen Protocol backend.

Authorize Device Initiates the secure, browser-based login flow to link your CLI to your Lumen account.

lum login

Contribute Code Analyzes, sanitizes, and submits the current project from your local machine to the Lumen network.

lum contribute

View History Displays the status of your last 10 contributions to the network.

lum history

De-authorize Device Logs out and securely removes the local authentication token.

lum logout

Local Prompt Generation

These commands do not send any data to the network.

Analyze Current Directory Assembles the current project into a prompt and copies it to your clipboard.

lum local

Save Prompt to File Saves the generated prompt to a .txt file instead of copying to the clipboard.

lum local -t my_project_prompt

Analyze a GitHub Repository Clones a public repo to a temporary directory for analysis.

lum local -g https://github.com/user/repo-name

Identify Token-Heavy Files Shows a leaderboard of the most token-consuming files.

# See the top 20 (default) files
lum local -l

# See the top 10 files
lum local -l 10

Configuration

Edit Configuration Opens your config.json file in your system's default text editor.

lum config --edit

Reset Configuration Resets all settings in config.json to their latest default values.

lum config --reset

---

Documentation

For detailed documentation on the Lumen Protocol, including the valuation engine, security practices, and our long-term vision, please visit our official documentation site.

• Installation Guide
• CLI Authentication
• Protocol Valuation Engine
• Security by Design
• The Lumen Whitepaper

Contributing

Contributions, issues, and feature requests are welcome! Please check the issues page and see CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License. See the LICENSE file for details.