docs: add project README
This commit is contained in:
@@ -0,0 +1,322 @@
|
||||
# Enuxia AI for Frappe
|
||||
|
||||
Local-first AI and RAG engine for the Frappe ecosystem, written in Rust and designed for edge inference.
|
||||
|
||||
> **Project status:** early development / pre-alpha.
|
||||
> This project is not ready for production use.
|
||||
|
||||
## Vision
|
||||
|
||||
Enuxia AI turns a Frappe environment into a permission-aware intelligent system capable of:
|
||||
|
||||
* searching internal documentation;
|
||||
* querying live business data;
|
||||
* understanding installed and custom DocTypes;
|
||||
* invoking controlled business tools;
|
||||
* producing answers with explicit sources;
|
||||
* running AI inference locally or on edge accelerators.
|
||||
|
||||
The project is designed to work with the broader Frappe ecosystem, including:
|
||||
|
||||
* ERPNext;
|
||||
* Frappe CRM;
|
||||
* Helpdesk;
|
||||
* Wiki;
|
||||
* HRMS;
|
||||
* custom Frappe applications.
|
||||
|
||||
## Principles
|
||||
|
||||
Enuxia AI is designed around the following principles:
|
||||
|
||||
* local-first processing;
|
||||
* data ownership;
|
||||
* least-privilege access;
|
||||
* permission-aware retrieval;
|
||||
* read-only access by default;
|
||||
* explicit validation before write operations;
|
||||
* no unrestricted SQL generated by an LLM;
|
||||
* auditable and sourced answers;
|
||||
* deployment without dependence on an external AI API.
|
||||
|
||||
## Current capabilities
|
||||
|
||||
The current pre-alpha implementation includes:
|
||||
|
||||
* a Rust workspace;
|
||||
* a command-line interface;
|
||||
* a Hailo-Ollama HTTP client;
|
||||
* local inference through a Hailo-10H accelerator;
|
||||
* an authenticated Frappe API client;
|
||||
* Frappe token authentication;
|
||||
* configurable model and API endpoints;
|
||||
* basic generation performance metrics.
|
||||
|
||||
## Planned architecture
|
||||
|
||||
```text
|
||||
Frappe applications
|
||||
ERPNext · CRM · Helpdesk · Wiki · HRMS · Custom Apps
|
||||
│
|
||||
▼
|
||||
Enuxia AI Frappe Bridge
|
||||
│
|
||||
HTTPS + permissions
|
||||
▼
|
||||
Enuxia AI — Rust
|
||||
┌──────────┴──────────┐
|
||||
│ │
|
||||
Retrieval and RAG Business tools
|
||||
Documents and data Controlled actions
|
||||
│ │
|
||||
└──────────┬──────────┘
|
||||
▼
|
||||
Local LLM
|
||||
│
|
||||
▼
|
||||
Hailo-Ollama / Hailo-10H
|
||||
```
|
||||
|
||||
## Workspace
|
||||
|
||||
```text
|
||||
enuxia-ai-frappe/
|
||||
├── apps/
|
||||
│ └── enuxia-ai-cli/
|
||||
│
|
||||
├── crates/
|
||||
│ ├── enuxia-frappe-client/
|
||||
│ └── enuxia-hailo-client/
|
||||
│
|
||||
├── Cargo.toml
|
||||
├── Cargo.lock
|
||||
├── LICENSE
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### `enuxia-ai-cli`
|
||||
|
||||
Command-line interface used during development to:
|
||||
|
||||
* list the available Hailo models;
|
||||
* send prompts to the local model;
|
||||
* verify Frappe authentication;
|
||||
* test the different Enuxia AI components.
|
||||
|
||||
### `enuxia-hailo-client`
|
||||
|
||||
Rust client responsible for communicating with Hailo-Ollama.
|
||||
|
||||
Current features:
|
||||
|
||||
* model discovery;
|
||||
* chat requests;
|
||||
* response deserialization;
|
||||
* generation duration;
|
||||
* token count;
|
||||
* average token throughput.
|
||||
|
||||
### `enuxia-frappe-client`
|
||||
|
||||
Authenticated Rust client for the Frappe API.
|
||||
|
||||
Current features:
|
||||
|
||||
* token authentication;
|
||||
* connection validation;
|
||||
* authenticated-user discovery.
|
||||
|
||||
Future versions will communicate primarily with the dedicated Enuxia AI Frappe Bridge.
|
||||
|
||||
## Development requirements
|
||||
|
||||
* Rust stable;
|
||||
* Cargo;
|
||||
* a reachable Hailo-Ollama server for hardware-accelerated inference;
|
||||
* a Frappe instance for integration testing;
|
||||
* a dedicated Frappe API user.
|
||||
|
||||
## Local configuration
|
||||
|
||||
Create a `.env` file at the repository root:
|
||||
|
||||
```env
|
||||
FRAPPE_BASE_URL=https://frappe.example.com
|
||||
FRAPPE_API_KEY=your_api_key
|
||||
FRAPPE_API_SECRET=your_api_secret
|
||||
```
|
||||
|
||||
The `.env` file is ignored by Git and must never be committed.
|
||||
|
||||
The Hailo endpoint can be selected through the command line:
|
||||
|
||||
```bash
|
||||
--hailo-base-url http://127.0.0.1:8000
|
||||
```
|
||||
|
||||
## Build and checks
|
||||
|
||||
Check the full workspace:
|
||||
|
||||
```bash
|
||||
cargo check --workspace
|
||||
```
|
||||
|
||||
Format the source code:
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Build an optimized release:
|
||||
|
||||
```bash
|
||||
cargo build --release --workspace
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### List available Hailo models
|
||||
|
||||
```bash
|
||||
cargo run -p enuxia-ai-cli -- models
|
||||
```
|
||||
|
||||
### Ask the local model a question
|
||||
|
||||
```bash
|
||||
cargo run -p enuxia-ai-cli -- \
|
||||
ask "Explain the purpose of a CRM."
|
||||
```
|
||||
|
||||
### Test Frappe authentication
|
||||
|
||||
```bash
|
||||
cargo run -p enuxia-ai-cli -- frappe whoami
|
||||
```
|
||||
|
||||
### Use a remote Hailo server
|
||||
|
||||
During development, Hailo-Ollama can run on a separate Raspberry Pi connected through a VPN or SSH tunnel.
|
||||
|
||||
Example tunnel:
|
||||
|
||||
```bash
|
||||
ssh -N \
|
||||
-L 18000:127.0.0.1:8000 \
|
||||
admin@raspberry-pi
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
cargo run -p enuxia-ai-cli -- \
|
||||
--hailo-base-url http://127.0.0.1:18000 \
|
||||
models
|
||||
```
|
||||
|
||||
The final production deployment is intended to run entirely on the edge server, without requiring the development computer.
|
||||
|
||||
## Security model
|
||||
|
||||
Enuxia AI must never bypass Frappe permissions.
|
||||
|
||||
The intended security model relies on:
|
||||
|
||||
* dedicated API users;
|
||||
* least-privilege roles;
|
||||
* permission-aware bridge endpoints;
|
||||
* explicit field and DocType allowlists;
|
||||
* read-only access by default;
|
||||
* human validation before sensitive actions;
|
||||
* no unrestricted LLM-generated SQL;
|
||||
* audit logs;
|
||||
* source references for generated answers;
|
||||
* exclusion of passwords, sessions, tokens and secrets from indexing.
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Foundation
|
||||
|
||||
* [x] Rust workspace
|
||||
* [x] Hailo-Ollama client
|
||||
* [x] Frappe API authentication
|
||||
* [x] command-line interface
|
||||
* [ ] configuration management
|
||||
* [ ] structured logging
|
||||
* [ ] automated tests
|
||||
|
||||
### Frappe integration
|
||||
|
||||
* [ ] installed-application discovery
|
||||
* [ ] accessible-DocType discovery
|
||||
* [ ] DocType metadata extraction
|
||||
* [ ] relationship discovery
|
||||
* [ ] permission-aware document retrieval
|
||||
* [ ] source references
|
||||
|
||||
### RAG
|
||||
|
||||
* [ ] document extraction
|
||||
* [ ] text chunking
|
||||
* [ ] embedding generation
|
||||
* [ ] vector indexing
|
||||
* [ ] hybrid retrieval
|
||||
* [ ] sourced answer generation
|
||||
|
||||
### Business tools
|
||||
|
||||
* [ ] controlled read tools
|
||||
* [ ] reporting tools
|
||||
* [ ] approval-gated write actions
|
||||
* [ ] audit trail
|
||||
* [ ] support for custom DocTypes
|
||||
|
||||
### Deployment
|
||||
|
||||
* [ ] local Rust API service
|
||||
* [ ] system service or container
|
||||
* [ ] ARM64 image
|
||||
* [ ] integration with the Frappe image
|
||||
* [ ] autonomous Raspberry Pi deployment
|
||||
* [ ] update and rollback strategy
|
||||
|
||||
## Related project
|
||||
|
||||
The permission-aware Frappe integration application is maintained separately:
|
||||
|
||||
`enuxia-ai-frappe-bridge`
|
||||
|
||||
## Contributing
|
||||
|
||||
The project is in an early architectural phase.
|
||||
|
||||
Before implementing a significant feature, open an issue to discuss:
|
||||
|
||||
* the use case;
|
||||
* the proposed architecture;
|
||||
* the security impact;
|
||||
* compatibility with Frappe permissions;
|
||||
* the intended tests.
|
||||
|
||||
See `CONTRIBUTING.md` for more details.
|
||||
|
||||
## Security
|
||||
|
||||
Do not report vulnerabilities through public issues.
|
||||
|
||||
See `SECURITY.md` for the private reporting process.
|
||||
|
||||
## License
|
||||
|
||||
Enuxia AI for Frappe is licensed under the GNU Affero General Public License v3.0 only.
|
||||
|
||||
See `LICENSE` for the complete licence text.
|
||||
Reference in New Issue
Block a user