# 🚀 Ripple Copilot CLI (`rpl`)

<p align="center">
  <a href="https://pypi.org/project/rplcopilot/"><img alt="PyPI" src="https://img.shields.io/pypi/v/rplcopilot?color=brightgreen"></a>
  <a href="https://github.com/Jorgecardenas1/rpl_render"><img alt="GitHub Repo" src="https://img.shields.io/badge/github-rpl--copilot-blue"></a>
  <a href="https://rplcopilot-docs.vercel.app"><img alt="Docs" src="https://img.shields.io/badge/docs-online-orange"></a>
</p>



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

---

## 📦 Installation

```bash
pip install rplcopilot
```

(Optional, for global access:)

```bash
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.

```bash
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


```bash
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.

```bash
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.

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

---

### 🔹 `rpl hybrid "<question>"`

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

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

Optional export:

```bash
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

```bash
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

```bash
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.

```bash
rpl ls
```

---

### 🔹 `rpl switch <project>`

Switch the active project context.

```bash
rpl switch metasurfaces
```

---

### 🔹 `rpl current`

Display the current project in context.

```bash
rpl current
```

---

### 🔹 `rpl push`

Prepares syncing payloads for a remote API.
Reports:

📁 Files to sync

📚 Metadata size

🧠 Embeddings (optional)

```bash
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!