Metadata-Version: 2.4
Name: circuitlens
Version: 0.1.1
Summary: CircuitLens AI visual electronics troubleshooting runtime
Author: CircuitLens
License-Expression: MIT
Keywords: electronics,troubleshooting,raspberry-pi,vlm,gemini
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 🔍 CircuitLens

## Local Cactus Hybrid VLM

CircuitLens can use Cactus as a local-first VLM and fall back to Gemini. Cactus exposes an OpenAI-compatible server, so install it and start a vision-capable model in a separate terminal:

```bash
brew install cactus-compute/cactus/cactus
cactus serve Cactus-Compute/gemma-4-e2b-it-hybrid --port 8080
```

Copy `.env.example` to `.env`, set `CACTUS_ENABLED=true`, and keep `AI_PROVIDER=hybrid`. The app will call Cactus at `http://127.0.0.1:8080/v1` first, then use Gemini if Cactus is unavailable. To require Cactus only, set `AI_PROVIDER=cactus`.

Recommended VLM choices:

- `Cactus-Compute/gemma-4-e2b-it-hybrid`: best fit for Cactus Hybrid because it includes confidence-based cloud handoff and vision support.
- `LiquidAI/LFM2-VL-450M`: smaller local VLM for lower memory use, without the same Cactus Hybrid handoff behavior.
- `gemini-3.1-pro-preview`: strongest cloud option already integrated in CircuitLens for detailed board analysis.

The existing `cactus run` command is interactive CLI usage. For CircuitLens integration, use `cactus serve`, which provides the HTTP endpoint consumed by the Vite server.

## Raspberry Pi Deployment

The Pi does not need Node.js or `npm`. Build the frontend on the development machine, then copy the generated `dist/` directory, `server.py`, and `.env` to the Pi. The Python runtime serves the UI and handles the Gemini/Cactus API routes:

```bash
# On the development machine
npm run build
scp -r dist server.py .env pi@<pi-ip>:/home/pi/circuitlens/

# On Raspberry Pi OS
cd ~/circuitlens
python3 server.py
```

Open `http://<pi-ip>:5173` from a browser on the Pi or another device on the same network. A USB or CSI camera and microphone can be used by the browser through the existing image and voice controls. For the Pi to use a local VLM, point `CACTUS_BASE_URL` at a Cactus server that supports the Pi architecture; otherwise set `AI_PROVIDER=gemini` or keep `AI_PROVIDER=hybrid` for cloud fallback.

### Single-device Pi 5 install

Copy the deployment files to the Pi once. After that, the Pi runs the complete device and starts the services on boot:

```bash
mkdir -p ~/circuitlens
# Copy dist/, server.py, .env, and rpi/ into ~/circuitlens first.
cd ~/circuitlens
sudo bash rpi/install.sh
sudo bash rpi/setup-cactus.sh
```

Use `AI_PROVIDER=hybrid` and `CACTUS_ENABLED=true` in `/opt/circuitlens/.env` for local Cactus first with Gemini fallback. For fully offline operation, use `AI_PROVIDER=cactus`, `CACTUS_ENABLED=true`, and `--no-cloud-handoff` is already enabled by the Cactus service. Check the device with:

```bash
systemctl status circuitlens cactus
curl http://127.0.0.1:5173/health
```

The Pi 5 is ARM64, which is the architecture expected by Cactus's native NEON runtime. The earlier Cactus failure happened only in x86-64 Kali WSL, not on the target Pi architecture.

## Python Package

The production frontend is bundled into a Python wheel. The wheel contains the Python runtime and built HTML/CSS/JavaScript files; it does not contain `node_modules` and does not require Node.js at runtime.

### Install From TestPyPI

Use this while testing the package before publishing it to the public PyPI index:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ circuitlens
circuitlens
```

If dependency resolution needs packages from normal PyPI as well, use:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ circuitlens
```

### Install From PyPI

After the package is published to the real PyPI index:

```bash
python -m pip install circuitlens
circuitlens
```

The command starts the local server at `http://0.0.0.0:5173`. Set `CIRCUITLENS_HOST` or `CIRCUITLENS_PORT` to change the bind address or port.

Create a `.env` file in the directory where you run `circuitlens` when using Gemini or Cactus:

```env
AI_PROVIDER=hybrid
CACTUS_ENABLED=true
CACTUS_BASE_URL=http://127.0.0.1:8080/v1
CACTUS_MODEL=Cactus-Compute/gemma-4-e2b-it-hybrid
GEMINI_API_KEY=replace_with_your_gemini_api_key
GEMINI_MODEL=gemini-3.1-pro-preview
```

For fully offline operation, use `AI_PROVIDER=cactus` and run a compatible local Cactus VLM. For Gemini-only operation, use `AI_PROVIDER=gemini`. The wheel does not include Cactus model weights.

### Build The Wheel

For maintainers, build it after building the frontend:

```bash
npm run build
python -m build --wheel --no-isolation --outdir wheelhouse
python -m venv package-test
package-test/bin/pip install wheelhouse/circuitlens-*.whl
package-test/bin/circuitlens
```

On Windows, use `package-test\\Scripts\\pip.exe` and `package-test\\Scripts\\circuitlens.exe`. The package name is `circuitlens`.

## AI Visual Electronics Troubleshooter

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![React](https://img.shields.io/badge/React-TypeScript-blue.svg)](https://react.dev/)
[![Vite](https://img.shields.io/badge/Vite-Fast%20Build-purple.svg)](https://vitejs.dev/)
[![Status](https://img.shields.io/badge/Status-MVP%20in%20Development-orange.svg)]()

> **CircuitLens is a phone-first AI electronics troubleshooting assistant that combines camera context, voice/text symptoms, multimodal AI and structured diagnostic reasoning to help engineers determine what to test next.**

CircuitLens is designed to bridge the gap between **seeing a physical hardware problem** and **knowing what to test next**.

The core workflow is:

**OBSERVE → HYPOTHESIZE → TEST → UPDATE → NEXT TEST**

---

# 📱 UI Preview

The following image represents the **proposed CircuitLens user interface and product direction**.

> **Concept UI — MVP in development**

<!--
    Add your UI screenshot here.

    Save your image as:
    assets/circuitlens-ui.png
-->

<p align="center">
  <img
    src="circuitlens.jpeg"
    alt="CircuitLens UI Preview"
    width="300"
  />
</p>

<p align="center">
  <i>Proposed CircuitLens mobile-first interface</i>
</p>

---

# 🎯 The Problem

Debugging electronics is still heavily dependent on engineering experience.

When a sensor, peripheral or embedded system fails, engineers commonly move between:

- Physical hardware
- Wiring
- Datasheets
- Firmware
- Serial logs
- Documentation
- Search engines
- Debugging tools

A typical troubleshooting workflow becomes:

```text
SYMPTOM
   ↓
INSPECT HARDWARE
   ↓
SEARCH DOCUMENTATION
   ↓
CHECK CODE
   ↓
GUESS POSSIBLE CAUSE
   ↓
RUN A TEST
   ↓
REPEAT
```

The physical hardware contains important information, but most existing troubleshooting workflows begin with text, logs or code.

### The result

- Physical context is easily lost.
- Engineers repeatedly switch between hardware and software.
- Beginners struggle to determine what to test first.
- Experienced engineers spend time diagnosing repetitive problems.
- Generic AI assistants often return long lists of possible causes instead of determining the most useful next action.

---

# 💡 Our Solution

## CircuitLens

CircuitLens turns an Android smartphone into a **visual engineering troubleshooting assistant**.

The user points the phone camera at an electronic setup and describes the problem through voice or text.

CircuitLens combines:

```text
CAMERA CONTEXT
       +
USER SYMPTOM
       +
HARDWARE CONTEXT
       +
TECHNICAL KNOWLEDGE
       +
PREVIOUS TEST RESULTS
```

to construct a structured diagnostic path.

### The user experience

1. **Inspect** the physical hardware using the phone camera.
2. **Describe** the problem using voice or text.
3. **Understand** the visible hardware and relevant context.
4. **Generate** competing fault hypotheses.
5. **Select** the Next Best Test.
6. **Perform** the test.
7. **Feed the result back** into the diagnostic engine.
8. **Update** the diagnosis and determine the next test.

---

# 🧠 Core Innovation

## From AI Answers → AI Investigation

A conventional AI assistant might respond:

> "Check your wiring, power supply, I²C address and sensor configuration."

CircuitLens is designed to go further.

Instead of asking:

> **"What could be wrong?"**

CircuitLens asks:

> **"Which test should I perform next to reduce uncertainty?"**

The diagnostic loop is:

```text
OBSERVE
   ↓
HYPOTHESIZE
   ↓
SELECT NEXT BEST TEST
   ↓
PERFORM TEST
   ↓
CAPTURE RESULT
   ↓
UPDATE HYPOTHESES
   ↓
SELECT NEXT TEST
```

This makes CircuitLens an **iterative diagnostic system**, rather than a one-shot chatbot.

---

# 🔧 Initial MVP Scenario

The initial MVP focuses on a real embedded-system setup:

### STM32F407G-DISC1

connected to:

### ADXL345 Accelerometer

using:

### I²C

Example problem:

> **"My ADXL345 is not giving the correct acceleration values."**

The system can consider possible causes such as:

| Priority | Hypothesis |
|---|---|
| High | I²C communication issue |
| High | Incorrect I²C address |
| Medium | Power / GND issue |
| Medium | Sensor configuration issue |

---

# 🔬 Example Diagnostic Workflow

## 1. Hardware Inspection

The phone camera observes the setup.

```text
STM32F407G-DISC1
        +
ADXL345
        +
I²C
```

The vision pipeline can identify relevant hardware and visible context.

---

## 2. Symptom Capture

The user says:

> "My ADXL345 is not giving the correct acceleration values."

The voice input is converted into structured symptom information.

---

## 3. Hypothesis Generation

CircuitLens generates candidate causes:

```text
01  I²C communication
02  Incorrect address
03  Power / GND
04  Sensor configuration
```

---

## 4. Next Best Test

Instead of presenting every possible fix, CircuitLens selects a diagnostic action.

```text
┌────────────────────────────────┐
│        NEXT BEST TEST          │
│                                │
│   Read ADXL345 DEVID register  │
│                                │
│   Expected result: 0xE5        │
└────────────────────────────────┘
```

The test is useful because its result can provide evidence about communication and addressing.

---

## 5. Result

Example:

```text
TEST RESULT

DEVID = 0x00
```

CircuitLens updates the diagnostic state.

```text
I²C COMMUNICATION     HIGH
I²C ADDRESS           HIGH
POWER / GND           MEDIUM
CONFIGURATION         LOWER
```

The system can then recommend:

```text
NEXT TEST

Verify SDA / SCL continuity
and confirm the I²C address.
```

The investigation continues until sufficient evidence is available.

---

# 📱 Phone-First Product Experience

The smartphone is not simply a display for a desktop application.

It acts as the primary sensing, interaction and guidance device.

```text
CAMERA
   ↓
PHYSICAL HARDWARE CONTEXT
   ↓
VOICE / TEXT SYMPTOM
   ↓
MULTIMODAL REASONING
   ↓
FAULT HYPOTHESES
   ↓
NEXT BEST TEST
   ↓
TEST RESULT
   ↓
UPDATED DIAGNOSIS
```

---

# 🏗️ System Architecture

CircuitLens is designed around a mobile-first architecture.

```text
                         ANDROID PHONE
                               │
                 ┌─────────────┴─────────────┐
                 │                           │
               CAMERA                      VOICE
                 │                           │
              CameraX                   Audio Input
                 │                           │
                 └─────────────┬─────────────┘
                               ↓
                      IMAGE PREPROCESSING
                               │
                    ┌──────────┴──────────┐
                    │                     │
                   OCR             LIGHTWEIGHT CV
                    │                     │
                    └──────────┬──────────┘
                               ↓
                      HARDWARE CONTEXT
                               │
                               ↓
                    LOCAL MULTIMODAL AI
                          Gemma 3n
                               │
                               ↓
                       STRUCTURED JSON
                               │
                               ↓
                     DIAGNOSTIC ENGINE
                               │
                    ┌──────────┴──────────┐
                    │                     │
               HYPOTHESES           TEST SELECTION
                    │                     │
                    └──────────┬──────────┘
                               ↓
                       NEXT BEST TEST
                               │
                               ↓
                          USER RESULT
                               │
                               └────────→ UPDATE
```

---

# 📲 Proposed Android Technology Stack

## Application

- Kotlin
- Jetpack Compose
- Android CameraX
- Android audio / voice input

## Computer Vision

- Image preprocessing
- Lightweight component detection
- OCR
- OpenCV where appropriate

## AI

- **Gemma 3n** — proposed local/open multimodal model
- Structured model output
- Evidence-aware reasoning

## Mobile Inference

Potential inference technologies include:

- LiteRT
- MediaPipe
- ONNX Runtime Mobile

## Optimization

- Model quantization
- Frame sampling
- Region-of-interest processing
- Tiered inference
- Asynchronous inference
- GPU/NPU acceleration where supported
- Memory-aware model loading
- Thermal and battery awareness

Actual performance metrics will be benchmarked during implementation rather than assumed.

---

# ⚙️ Mobile AI Strategy

Running multimodal AI locally on a smartphone requires careful resource management.

## Model Quantization

Reduce model size and computational requirements where appropriate.

## Frame Sampling

Avoid running expensive inference on every camera frame.

```text
CAMERA STREAM
      ↓
LIGHTWEIGHT PROCESSING
      ↓
RELEVANT FRAME
      ↓
AI REASONING
```

## Region of Interest

Focus computation on relevant hardware regions rather than the entire image.

## Tiered Inference

Use lightweight perception frequently and invoke heavier multimodal reasoning only when necessary.

## Asynchronous Inference

Keep the Android interface responsive while inference is running.

## Hardware Acceleration

Use available GPU/NPU acceleration where supported by the device and inference framework.

## Thermal and Memory Management

Perform expensive inference only when required and manage model resources according to device constraints.

---

# 🧩 Structured AI Output

The AI reasoning layer is designed to return structured information rather than directly controlling the application interface.

Example:

```json
{
  "hardware": [
    "STM32F407G-DISC1",
    "ADXL345"
  ],
  "interface": "I2C",
  "symptom": "Incorrect acceleration values",
  "hypotheses": [
    {
      "name": "I2C communication issue",
      "priority": "high"
    },
    {
      "name": "Incorrect address",
      "priority": "high"
    }
  ],
  "next_test": {
    "name": "Read ADXL345 DEVID",
    "expected": "0xE5"
  }
}
```

The Android application can interpret this structured output and render a predictable diagnostic interface.

---

# 🧠 Diagnostic Engine

The AI model is responsible for understanding the available information and generating candidate hypotheses.

The diagnostic engine is responsible for:

- Maintaining diagnostic state
- Tracking evidence
- Ranking hypotheses
- Selecting diagnostic tests
- Processing test results
- Updating the investigation

This separation is intended to make the system more controllable and explainable than a pure conversational AI architecture.

---

# 📷 Why the Phone Is Essential

CircuitLens is designed around the capabilities of a modern smartphone.

| Phone Capability | CircuitLens Usage |
|---|---|
| Camera | Physical hardware inspection |
| Microphone | Voice-based symptom input |
| Processing | Mobile AI/CV workloads |
| Display | Guided diagnostic procedures |
| On-device AI | Local/private reasoning path |
| Connectivity | Optional engineering workflows |

The goal is:

> **Make the phone an engineering diagnostic instrument.**

---

# 💻 Office Kit Workflow

CircuitLens can bridge phone-based physical inspection with laptop-based engineering workflows.

Potential engineering artifacts include:

- Hardware images
- Diagnostic results
- Voice notes
- Test history
- Firmware
- Serial logs
- Datasheets
- Source code
- Diagnostic reports

Conceptual workflow:

```text
                         PHONE
                           │
              ┌────────────┴────────────┐
              │                         │
           CAMERA                   DIAGNOSIS
              │                         │
              └────────────┬────────────┘
                           ↓
                       OFFICE KIT
                           ↓
                         LAPTOP
                           │
              ┌────────────┼────────────┐
              ↓            ↓            ↓
          Firmware        Logs      Datasheets
```

---

# 🎯 Target Users

## Embedded Engineers

Investigate board and peripheral problems faster.

## Students & Makers

Learn structured electronics troubleshooting.

## Robotics Engineers

Investigate sensors, controllers and communication interfaces.

## Laboratory Engineers

Diagnose recurring equipment problems.

## Field Technicians

Use a phone as a portable troubleshooting assistant.

---

# 🚀 MVP Scope

The initial implementation is deliberately constrained.

### Initial Hardware Focus

```text
STM32
   +
Common Sensors
   +
I²C
   +
Defined Diagnostic Procedures
```

The goal is not to claim that CircuitLens can diagnose every circuit.

The MVP will first validate the workflow against known embedded-system scenarios.

### Future Expansion

```text
EMBEDDED SYSTEMS
        ↓
       IoT
        ↓
    ROBOTICS
        ↓
LAB EQUIPMENT
        ↓
INDUSTRIAL FIELD SERVICE
```

---

# 🛠️ Development Roadmap

### Phase 1 — Mobile Interface

Camera, symptom input and diagnostic UI.

### Phase 2 — Hardware Context

Component recognition, OCR and image processing.

### Phase 3 — Multimodal AI

Integrate a mobile-capable local/open multimodal model.

### Phase 4 — Diagnostic Engine

Implement hypothesis generation, ranking and test selection.

### Phase 5 — Closed-Loop Diagnosis

Feed test results back into the diagnostic state.

### Phase 6 — Phone/Laptop Workflow

Integrate Office Kit and engineering artifacts.

### Phase 7 — Real Hardware Validation

Validate against real STM32 + sensor failure scenarios.

---

# ⚠️ Engineering Challenges

| Challenge | Approach |
|---|---|
| Local model compute requirements | Quantization + tiered inference |
| Ambiguous wiring | Begin with constrained hardware setups |
| Vision uncertainty | Combine visual context with user input |
| AI hallucination | Structured outputs + diagnostic constraints |
| Incorrect diagnosis | Closed-loop testing |
| Thermal limitations | Asynchronous / demand-based inference |
| Limited MVP development time | Focus on STM32 + ADXL345 first |

---

# 📊 Current Development Status

CircuitLens is currently being developed as a hackathon MVP.

### Concept & Planning

- [x] Product concept
- [x] Diagnostic workflow
- [x] Next Best Test concept
- [x] Initial hardware scenario
- [x] Android architecture
- [x] Initial UI direction

### Prototype

- [ ] Interactive camera inspection
- [ ] Hardware-context pipeline
- [ ] Diagnostic reasoning engine
- [ ] Next Best Test engine
- [ ] Closed-loop test updates
- [ ] Voice interaction

### Production Path

- [ ] Local multimodal model integration
- [ ] Android implementation
- [ ] Mobile inference optimization
- [ ] Real hardware validation
- [ ] Office Kit workflow

---

# 🧪 Prototype Strategy

The first prototype focuses on proving the core diagnostic interaction rather than attempting universal electronics diagnosis.

The intended workflow is:

```text
LAUNCH CIRCUITLENS
        ↓
INSPECT HARDWARE
        ↓
IDENTIFY CONTEXT
        ↓
ENTER / SPEAK SYMPTOM
        ↓
GENERATE HYPOTHESES
        ↓
SELECT NEXT BEST TEST
        ↓
ENTER TEST RESULT
        ↓
UPDATE DIAGNOSIS
        ↓
SELECT NEXT TEST
```

Where deterministic prototype logic is used during development, it will be clearly distinguished from real AI inference.

---

# 🔮 Future Vision

CircuitLens starts with embedded-system troubleshooting.

The long-term vision is to help engineers understand physical systems using multimodal AI.

Potential applications include:

- Embedded systems
- IoT devices
- Robotics
- Industrial automation
- Laboratory equipment
- Electronics repair
- Field maintenance

### Long-term Vision

> **Bridge the gap between seeing an engineering problem and knowing what to test next.**

---

# 🏆 Hackathon

Built for:

## iQOO Hackathon — Open Innovation Track

CircuitLens focuses on:

- Physical-world AI
- Multimodal interaction
- Mobile/on-device AI
- Android
- Computer vision
- Embedded systems
- AI-assisted diagnostics
- Phone-first engineering workflows

---

# 👨‍💻 Developer

## Samarth Ratnaparkhi

Solo developer with hands-on engineering experience across:

- Embedded systems
- STM32
- Sensors
- I²C
- Computer vision
- AI/ML
- Robotics
- Industrial camera systems
- Hardware/software integration

CircuitLens builds on this engineering experience to explore a phone-first AI diagnostic workflow for physical electronics.

---

# 📦 Getting Started

## Prerequisites

Make sure the following are installed:

- Node.js 18+
- npm
- Git

Check your installations:

```bash
node --version
npm --version
git --version
```

---

## Clone the Repository

```bash
git clone https://github.com/Samarth-07-14/CircuitLens.git
```

Enter the project directory:

```bash
cd CircuitLens
```

---

## Install Dependencies

```bash
npm install
```

---

## Start the Development Server

```bash
npm run dev
```

Vite will start the development server.

Open the URL shown in the terminal, typically:

```text
http://localhost:5173
```

---

## Build for Production

```bash
npm run build
```

---

## Preview the Production Build

```bash
npm run preview
```

---

# 🔄 Development Workflow

Clone the project:

```bash
git clone https://github.com/Samarth-07-14/CircuitLens.git
cd CircuitLens
```

Install dependencies:

```bash
npm install
```

Start development:

```bash
npm run dev
```

After making changes:

```bash
git status
git add .
git commit -m "Update CircuitLens prototype"
git push
```

---

# 📁 Project Structure

```text
CircuitLens/
│
├── public/
│
├── assets/
│   └── circuitlens-ui.png
│
├── src/
│   ├── components/
│   ├── pages/
│   ├── data/
│   ├── logic/
│   └── ...
│
├── index.html
├── package.json
├── package-lock.json
├── vite.config.ts
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
├── tailwind.config.ts
├── postcss.config.js
├── eslint.config.js
└── README.md
```

---

# 🤝 Development Priorities

The project is being developed with the following priorities:

1. Working diagnostic workflow
2. High-quality mobile UI
3. Real camera interaction
4. Reliable diagnostic state management
5. Multimodal AI integration
6. Local/on-device inference
7. Real hardware validation

---

# 📜 License

This project is licensed under the MIT License.

Third-party libraries, frameworks, models and open-source components retain their respective licenses.

---

<p align="center">

# 🔍 CIRCUITLENS

### See the hardware. Understand the problem. Test what matters.

**Point. Ask. Test.**

</p>
