🚀 Ripple Copilot CLI (rpl)

Your AI-powered lab assistant, right in the terminal.
Log experiments, upload documents, and build a smart, searchable knowledge base — with zero friction.

---

📦 Installation

pip install rplcopilot

(Optional, for global access:)

chmod +x rpl.py
ln -s $(pwd)/rpl.py /usr/local/bin/rpl

---

🧪 Commands

🔹 rpl init <project>

Create a new project in the current directory.

rpl init quantum --description "Quantum film experiments"

📁 Project Structure

your-lab-project/
└── .rpl/
    ├── config.json               # Global pointer to current project
    └── projects/
        └── <project-name>/
            ├── metadata.json     # File info + summaries
            ├── logs/             # Individual experiment logs
            ├── uploads/          # Uploaded raw files
            └── faiss_index/      # Vector store

---

🔹 rpl log

Log an experiment with rich metadata. Flags:

--title – Title of the experiment (required)

--notes – Full notes or description

--tags – Comma-separated tags or keywords

rpl log --title "Day 1" --notes "Tested sapphire substrate." --tags "GHz,permittivity"

---

🔹 rpl upload <file_or_folder>

Upload and embed documents. Handles PDFs, scanned files, papers.

rpl upload notes.pdf
rpl upload ./papers/

Includes:

• Chunking + embeddings (FAISS)
• Semantic enrichment (summary, keywords, type detection)

---

🔹 rpl query "<question>"

Ask natural language questions against indexed documents.

rpl query "What trends were found using sapphire substrates?"

---

🔹 rpl hybrid "<question>"

Run hybrid search (BM25 + vector similarity) for improved retrieval.

rpl hybrid "Show experiments on dielectric response at 10 GHz"

Optional export:

rpl hybrid "sapphire films" --export json
rpl hybrid "quantum well" --export bib
rpl hybrid "mid-IR optics" --export tex

⚖️ Combines symbolic + vector retrieval. Great for exact terms and fuzzy matches.

---

🔹 rpl digest

Generate a digest-style summary of uploaded files. Includes:

📄 File name

🧠 Summary (LLM-generated)

🏷️ Keywords

rpl digest --format md

---

🔹 rpl trace "<concept>"

Trace a concept or keyword across all indexed files. Flags:

--k – Number of top documents (default: 10)

--format – Export format: md, json, or bib

rpl trace "sapphire substrate" --format md

🔍 Outputs all occurrences with context, source, and exportable summary.

---

🔹 rpl ls

List all available .rpl projects found in subdirectories.

rpl ls

---

🔹 rpl switch <project>

Switch the active project context.

rpl switch metasurfaces

---

🔹 rpl current

Display the current project in context.

rpl current

---

🔹 rpl push

Prepares syncing payloads for a remote API. Reports:

📁 Files to sync

📚 Metadata size

🧠 Embeddings (optional)

rpl push

---

📤 Export Formats

• .json — audit log of search results
• .bib — BibTeX citation (autogenerated)
• .tex — ready-to-include experiment snippets for LaTeX

---

📬 Coming Soon

• rpl pull — download remote project

• rpl auth — API key authentication

• rpl dashboard - interactive Streamlit viewer

• rpl bib - manage BibTeX citations + export

• Web UI — view, filter, and explore experiments

• Multi-user collaboration & versioning

---

👩‍🔬 Ideal For:

• Scientific labs
• Industrial research
• Long term experiment tracking
• Biotech, nanotech, or AI-assisted experiments
• Research labs and PhDs
• For student to learn the research workflow

---

🧠 Credits

Crafted with ❤️ by the Ripple Copilot team
We welcome pull requests, feedback, and ideas!