ragfs_fuse/
lib.rs

1//! FUSE filesystem implementation for RAGFS.
2//!
3//! This crate provides a FUSE (Filesystem in Userspace) interface that allows
4//! semantic search capabilities and agent file operations to be accessed through
5//! standard filesystem operations.
6//!
7//! # Features
8//!
9//! - **Passthrough**: Real files are accessible at their original locations
10//! - **Virtual Query Interface**: Special `.ragfs/` directory for semantic queries
11//! - **Agent Operations**: Structured file operations via `.ops/` with JSON feedback
12//! - **Safety Layer**: Soft delete, audit logging, and undo via `.safety/`
13//! - **Semantic Operations**: AI-powered file organization via `.semantic/`
14//!
15//! # Virtual Directory Structure
16//!
17//! ```text
18//! /mountpoint/
19//! ├── real_files/                # Passthrough to source directory
20//! │
21//! └── .ragfs/                    # Virtual control directory
22//!     ├── .query/<text>          # Semantic query → JSON results
23//!     ├── .search/<text>         # Search results
24//!     ├── .similar/<path>        # Find similar files
25//!     ├── .index                 # Index statistics (JSON)
26//!     ├── .config                # Current configuration (JSON)
27//!     ├── .reindex               # Write path to trigger reindex
28//!     ├── .help                  # Usage documentation
29//!     │
30//!     ├── .ops/                  # Agent file operations
31//!     │   ├── .create            # Write: "path\ncontent"
32//!     │   ├── .delete            # Write: "path"
33//!     │   ├── .move              # Write: "src\ndst"
34//!     │   ├── .batch             # Write: JSON BatchRequest
35//!     │   └── .result            # Read: JSON OperationResult
36//!     │
37//!     ├── .safety/               # Protection layer
38//!     │   ├── .trash/            # Soft-deleted files (recoverable)
39//!     │   ├── .history           # Audit log (JSONL)
40//!     │   └── .undo              # Write: operation_id to undo
41//!     │
42//!     └── .semantic/             # AI-powered operations
43//!         ├── .organize          # Write: OrganizeRequest JSON
44//!         ├── .similar           # Write: path → find similar
45//!         ├── .cleanup           # Read: CleanupAnalysis JSON
46//!         ├── .dedupe            # Read: DuplicateGroups JSON
47//!         ├── .pending/          # Proposed plans directory
48//!         ├── .approve           # Write: plan_id to execute
49//!         └── .reject            # Write: plan_id to cancel
50//! ```
51//!
52//! # Basic Usage
53//!
54//! ```bash
55//! # Mount the filesystem
56//! ragfs mount /source /mnt/ragfs -f
57//!
58//! # Query via filesystem
59//! cat "/mnt/ragfs/.ragfs/.query/how to authenticate"
60//!
61//! # Check index status
62//! cat /mnt/ragfs/.ragfs/.index
63//! ```
64//!
65//! # Agent Operations (.ops/)
66//!
67//! ```bash
68//! # Create a file with feedback
69//! echo -e "docs/new.md\n# New Document" > /mnt/ragfs/.ragfs/.ops/.create
70//! cat /mnt/ragfs/.ragfs/.ops/.result  # JSON result with undo_id
71//!
72//! # Delete a file (uses soft delete)
73//! echo "docs/old.md" > /mnt/ragfs/.ragfs/.ops/.delete
74//!
75//! # Move/rename a file
76//! echo -e "old/path.txt\nnew/path.txt" > /mnt/ragfs/.ragfs/.ops/.move
77//!
78//! # Batch operations
79//! echo '{"operations":[{"Create":{"path":"a.txt","content":"A"}}],"atomic":true}' \
80//!     > /mnt/ragfs/.ragfs/.ops/.batch
81//! ```
82//!
83//! # Safety Layer (.safety/)
84//!
85//! ```bash
86//! # View operation history
87//! cat /mnt/ragfs/.ragfs/.safety/.history
88//!
89//! # List deleted files in trash
90//! ls /mnt/ragfs/.ragfs/.safety/.trash/
91//!
92//! # Undo an operation
93//! echo "550e8400-e29b-41d4-a716-446655440000" > /mnt/ragfs/.ragfs/.safety/.undo
94//!
95//! # Restore from trash (write "restore" to trash entry)
96//! echo "restore" > /mnt/ragfs/.ragfs/.safety/.trash/<uuid>
97//! ```
98//!
99//! # Semantic Operations (.semantic/)
100//!
101//! ```bash
102//! # Find files similar to a given file
103//! echo "src/main.rs" > /mnt/ragfs/.ragfs/.semantic/.similar
104//! cat /mnt/ragfs/.ragfs/.semantic/.similar  # JSON results
105//!
106//! # Propose file organization
107//! echo '{"scope":"docs/","strategy":"by_topic"}' > /mnt/ragfs/.ragfs/.semantic/.organize
108//!
109//! # Review pending plans
110//! ls /mnt/ragfs/.ragfs/.semantic/.pending/
111//! cat /mnt/ragfs/.ragfs/.semantic/.pending/<plan_id>
112//!
113//! # Approve or reject a plan
114//! echo "<plan_id>" > /mnt/ragfs/.ragfs/.semantic/.approve
115//! echo "<plan_id>" > /mnt/ragfs/.ragfs/.semantic/.reject
116//!
117//! # View cleanup analysis
118//! cat /mnt/ragfs/.ragfs/.semantic/.cleanup
119//!
120//! # View duplicate detection
121//! cat /mnt/ragfs/.ragfs/.semantic/.dedupe
122//! ```
123//!
124//! # Rust API Example
125//!
126//! ```rust,ignore
127//! use ragfs_fuse::RagFs;
128//!
129//! // Create filesystem with full RAG capabilities
130//! let fs = RagFs::with_rag(source_path, store, embedder, runtime, reindex_sender);
131//!
132//! // Mount
133//! fuser::mount2(fs, mountpoint, &options)?;
134//! ```
135
136pub mod filesystem;
137pub mod inode;
138pub mod ops;
139pub mod safety;
140pub mod semantic;
141
142pub use filesystem::RagFs;
143pub use inode::{InodeKind, InodeTable};
144pub use ops::{BatchRequest, BatchResult, Operation, OperationResult, OpsManager};
145pub use safety::{
146    HistoryEntry, HistoryOperation, SafetyConfig, SafetyManager, TrashEntry, UndoData,
147};
148pub use semantic::{
149    CleanupAnalysis, DuplicateGroups, OrganizeRequest, OrganizeStrategy, SemanticConfig,
150    SemanticManager, SemanticPlan, SimilarFilesResult,
151};
ragfs_fuse/lib.rs

ragfs_fuse/
lib.rs
