pylumen 2.0.0

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 is a dual-purpose CLI designed for developers. It began as a powerful local tool to solve the tedious process of manual context building for LLMs and evolved into a gateway for developers to ethically contribute to the AI data economy.

1. A Best-in-Class Local Prompt Helper: A 100% private utility for your daily AI-assisted development.
2. A Gateway to the Data Economy: A secure bridge to the Lumen Protocol, allowing developers to ethically contribute their anonymized code and earn rewards.

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, ignores dotfiles, parses Jupyter Notebooks (.ipynb) (locally), and uses an optimized / custom-built + unique 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 manage context window limitations.
• Customizable Filtering: Use the CLI or 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.
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 occurs when the pip scripts directory is not in your system's PATH.

• Quick Fix: Run the tool as a Python module: python -m lum --version.
• Permanent Fix (Recommended):
  • macOS/Linux: Find your Python script path (often ~/.local/bin) and add it to your shell configuration (~/.zshrc, ~/.bashrc): export PATH="$HOME/.local/bin:$PATH". Restart your terminal.
  • Windows: Reinstall Python and ensure the "Add Python to PATH" checkbox is selected.

Commands

Network Commands

These commands interact with the Lumen Protocol backend.

Authorize Device Initiates the secure login flow to link your CLI to a Lumen account.

lum login

Contribute Code Analyzes, sanitizes, and submits the current project to the Lumen network.

lum contribute

View History Displays the status of your last 10 contributions.

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 project into a prompt and copies it to your clipboard.

lum local

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

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 config.json in your system's default text editor.

lum config --edit

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

lum config --reset

Set a Specific Value Changes a single setting directly from the terminal.

# Enable a boolean setting
lum config --set use_ai_instructions true

# Overwrite a list (provide as a comma-separated string)
lum config --set skipped_files ".DS_Store,yarn.lock"

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 details.

License

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