Reworked FileSystemProvider (#557)

Co-authored-by: Semyon Proshev <[email protected]>

Author: petuch03

agents/agents-features/agents-features-memory/src/commonMain/kotlin/ai/koog/agents/memory/providers/LocalFileMemoryProvider.kt

@@ -133,7 +133,7 @@ public data class LocalFileMemoryProvider<Path>(
             is MemoryScope.Product -> listOf("product", scope.name, "subject", subject.name)
             MemoryScope.CrossProduct -> listOf("organization", "subject", subject.name)
         }
-        return segments.fold(root) { acc, segment -> fs.fromRelativeString(acc, segment) }
+        return segments.fold(root) { acc, segment -> fs.joinPath(acc, segment) }
     }
 
     /**
@@ -202,7 +202,7 @@ public data class LocalFileMemoryProvider<Path>(
      */
     override suspend fun save(fact: Fact, subject: MemorySubject, scope: MemoryScope) {
         val path = getStoragePath(subject, scope)
-        storage.createDirectories(fs.fromRelativeString(root, config.storageDirectory))
+        storage.createDirectories(fs.joinPath(root, config.storageDirectory))
 
         val facts = loadFacts(path).toMutableMap()
         val key = fact.concept.keyword

agents/agents-features/agents-features-memory/src/commonMain/kotlin/ai/koog/agents/memory/storage/Storage.kt

@@ -1,7 +1,10 @@
 package ai.koog.agents.memory.storage
 
-import ai.koog.rag.base.files.FileMetadata
 import ai.koog.rag.base.files.FileSystemProvider
+import ai.koog.rag.base.files.createDirectory
+import ai.koog.rag.base.files.createFile
+import ai.koog.rag.base.files.readText
+import ai.koog.rag.base.files.writeText
 
 /**
  * Platform-independent encryption abstraction for secure data storage.
@@ -181,7 +184,7 @@ public open class SimpleStorage<Path>(
      */
     override suspend fun read(path: Path): String? {
         if (!fs.exists(path)) return null
-        return fs.read(path).decodeToString()
+        return fs.readText(path)
     }
 
     /**
@@ -201,9 +204,9 @@ public open class SimpleStorage<Path>(
         val name = fs.name(path)
 
         if (!fs.exists(path)) {
-            fs.create(parent, name, FileMetadata.FileType.File)
+            fs.createFile(fs.joinPath(parent, name))
         }
-        fs.write(path, content.encodeToByteArray())
+        fs.writeText(path, content)
     }
 
     /**
@@ -220,7 +223,7 @@ public open class SimpleStorage<Path>(
         if (!fs.exists(path)) {
             val parent = fs.parent(path) ?: return
             val name = fs.name(path)
-            fs.create(parent, name, FileMetadata.FileType.Directory)
+            fs.createDirectory(fs.joinPath(parent, name))
         }
     }
 }
@@ -282,7 +285,7 @@ public class EncryptedStorage<Path>(
      */
     override suspend fun read(path: Path): String? {
         if (!fs.exists(path)) return null
-        val content = fs.read(path).decodeToString()
+        val content = fs.readText(path)
         return encryption.decrypt(content)
     }
 
@@ -305,9 +308,9 @@ public class EncryptedStorage<Path>(
 
         val encrypted = encryption.encrypt(content)
         if (!fs.exists(path)) {
-            fs.create(parent, name, FileMetadata.FileType.File)
+            fs.createFile(fs.joinPath(parent, name))
         }
-        fs.write(path, encrypted.encodeToByteArray())
+        fs.writeText(path, encrypted)
     }
 
     /**
@@ -323,7 +326,7 @@ public class EncryptedStorage<Path>(
         if (!fs.exists(path)) {
             val parent = fs.parent(path) ?: return
             val name = fs.name(path)
-            fs.create(parent, name, FileMetadata.FileType.Directory)
+            fs.createDirectory(fs.joinPath(parent, name))
         }
     }
 }

agents/agents-features/agents-features-memory/src/jvmTest/kotlin/ai/koog/agents/memory/storage/JvmStorageTest.kt

@@ -1,6 +1,7 @@
 package ai.koog.agents.memory.storage
 
 import ai.koog.rag.base.files.JVMFileSystemProvider
+import ai.koog.rag.base.files.readText
 import kotlinx.coroutines.test.runTest
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.io.TempDir
@@ -21,7 +22,7 @@ class JvmStorageTest {
         val storage = EncryptedStorage(fs, encryptor)
 
         // Test file creation and writing
-        val testPath = fs.fromRelativeString(tempDir, "test.txt")
+        val testPath = fs.joinPath(tempDir, "test.txt")
         val testContent = "Hello, World!"
         storage.write(testPath, testContent)
 
@@ -33,23 +34,23 @@ class JvmStorageTest {
         assertEquals(testContent, readContent)
 
         // Test directory creation
-        val dirPath = fs.fromRelativeString(tempDir, "test/nested/dir")
+        val dirPath = fs.joinPath(tempDir, "test/nested/dir")
         storage.createDirectories(dirPath)
         assertTrue(storage.exists(dirPath))
 
         // Test file in nested directory
-        val nestedPath = fs.fromRelativeString(tempDir, "test/nested/dir/nested.txt")
+        val nestedPath = fs.joinPath(tempDir, "test/nested/dir/nested.txt")
         storage.write(nestedPath, testContent)
         assertTrue(storage.exists(nestedPath))
         assertEquals(testContent, storage.read(nestedPath))
 
         // Test non-existent file
-        val nonExistentPath = fs.fromRelativeString(tempDir, "non-existent.txt")
+        val nonExistentPath = fs.joinPath(tempDir, "non-existent.txt")
         assertFalse(storage.exists(nonExistentPath))
         assertEquals(null, storage.read(nonExistentPath))
 
         // Test encryption
-        val encryptedContent = fs.read(testPath).decodeToString()
+        val encryptedContent = fs.readText(testPath)
         assertFalse(encryptedContent.contains(testContent), "Content should be encrypted")
     }
 

agents/agents-features/agents-features-snapshot/src/commonMain/kotlin/ai/koog/agents/snapshot/providers/file/FilePersistencyStorageProvider.kt

@@ -2,8 +2,10 @@ package ai.koog.agents.snapshot.providers.file
 
 import ai.koog.agents.snapshot.feature.AgentCheckpointData
 import ai.koog.agents.snapshot.providers.PersistencyStorageProvider
-import ai.koog.rag.base.files.FileMetadata
 import ai.koog.rag.base.files.FileSystemProvider
+import ai.koog.rag.base.files.createDirectory
+import ai.koog.rag.base.files.readText
+import ai.koog.rag.base.files.writeText
 import kotlinx.serialization.json.Json
 
 /**
@@ -27,9 +29,9 @@ public open class FilePersistencyStorageProvider<Path>(
      * Directory where agent checkpoints are stored
      */
     private suspend fun checkpointsDir(): Path {
-        val dir = fs.fromRelativeString(root, "checkpoints")
+        val dir = fs.joinPath(root, "checkpoints")
         if (!fs.exists(dir)) {
-            fs.create(root, "checkpoints", FileMetadata.FileType.Directory)
+            fs.createDirectory(dir)
         }
         return dir
     }
@@ -39,9 +41,9 @@ public open class FilePersistencyStorageProvider<Path>(
      */
     private suspend fun agentCheckpointsDir(): Path {
         val checkpointsDir = checkpointsDir()
-        val agentDir = fs.fromRelativeString(checkpointsDir, persistenceId)
+        val agentDir = fs.joinPath(checkpointsDir, persistenceId)
         if (!fs.exists(agentDir)) {
-            fs.create(checkpointsDir, persistenceId, FileMetadata.FileType.Directory)
+            fs.createDirectory(agentDir)
         }
         return agentDir
     }
@@ -51,7 +53,7 @@ public open class FilePersistencyStorageProvider<Path>(
      */
     private suspend fun checkpointPath(checkpointId: String): Path {
         val agentDir = agentCheckpointsDir()
-        return fs.fromRelativeString(agentDir, checkpointId)
+        return fs.joinPath(agentDir, checkpointId)
     }
 
     override suspend fun getCheckpoints(): List<AgentCheckpointData> {
@@ -63,7 +65,7 @@ public open class FilePersistencyStorageProvider<Path>(
 
         return fs.list(agentDir).mapNotNull { path ->
             try {
-                val content = fs.read(path).decodeToString()
+                val content = fs.readText(path)
                 json.decodeFromString<AgentCheckpointData>(content)
             } catch (_: Exception) {
                 null
@@ -74,7 +76,7 @@ public open class FilePersistencyStorageProvider<Path>(
     override suspend fun saveCheckpoint(agentCheckpointData: AgentCheckpointData) {
         val checkpointPath = checkpointPath(agentCheckpointData.checkpointId)
         val serialized = json.encodeToString(AgentCheckpointData.serializer(), agentCheckpointData)
-        fs.write(checkpointPath, serialized.encodeToByteArray())
+        fs.writeText(checkpointPath, serialized)
     }
 
     override suspend fun getLatestCheckpoint(): AgentCheckpointData? {

rag/rag-base/src/commonMain/kotlin/ai/koog/rag/base/files/Extensions.kt

@@ -20,3 +20,75 @@ private fun <Path> Path.components(fs: FileSystemProvider.ReadOnly<Path>): List<
         }
     }.asReversed()
 }
+
+/**
+ * Reads the entire content of a file as a string.
+ *
+ * @param path The file path to read.
+ * @param documentProvider document provider to get unsaved text from.
+ * @return The file content as a string.
+ *
+ * @see [FileSystemProvider.ReadOnly.readBytes]
+ * @see [DocumentProvider.document]
+ * @see [DocumentProvider.text]
+ */
+public suspend fun <Path, Document> FileSystemProvider.ReadOnly<Path>.readText(
+    path: Path,
+    documentProvider: DocumentProvider<Path, Document>?
+): String {
+    if (documentProvider != null) {
+        val document = documentProvider.document(path)
+        if (document != null) {
+            return documentProvider.text(document).toString()
+        }
+    }
+    return readBytes(path).decodeToString()
+}
+
+/**
+ * Reads the entire content of a file as a string.
+ *
+ * @param path The file path to read.
+ * @return The file content as a string.
+ *
+ * @see [FileSystemProvider.ReadOnly.readBytes]
+ */
+public suspend fun <Path> FileSystemProvider.ReadOnly<Path>.readText(path: Path): String {
+    return readBytes(path).decodeToString()
+}
+
+/**
+ * Writes a string to a file, replacing any existing content.
+ *
+ * @param path The file path to write to.
+ * @param content The string content to write.
+ *
+ * @see [FileSystemProvider.ReadWrite.writeBytes]
+ */
+public suspend fun <Path> FileSystemProvider.ReadWrite<Path>.writeText(path: Path, content: String) {
+    writeBytes(path, content.encodeToByteArray())
+}
+
+/**
+ * Creates a file at the specified [path].
+ * Parent directories will be created automatically if they don't exist.
+ *
+ * @param path The path where the file should be created.
+ *
+ * @see [FileSystemProvider.ReadWrite.create]
+ */
+public suspend fun <Path> FileSystemProvider.ReadWrite<Path>.createFile(path: Path) {
+    create(path, FileMetadata.FileType.File)
+}
+
+/**
+ * Creates a directory at the specified [path].
+ * Parent directories will be created automatically if they don't exist.
+ *
+ * @param path The path where the directory should be created.
+ *
+ * @see [FileSystemProvider.ReadWrite.create]
+ */
+public suspend fun <Path> FileSystemProvider.ReadWrite<Path>.createDirectory(path: Path) {
+    create(path, FileMetadata.FileType.Directory)
+}