Use local knowledge service

.env.example

@@ -0,0 +1,45 @@
+# Agentlang CLI - Environment Configuration
+# Copy this file to .env and update values as needed
+
+# =============================================================================
+# Knowledge Service Configuration (Option 2: External Service)
+# =============================================================================
+# The URL of the running knowledge-service
+# Set this to connect to a local knowledge-service instance
+KNOWLEDGE_SERVICE_URL=http://localhost:8080
+
+# Note: In this architecture, knowledge-service runs as a separate process.
+# You must start it manually before running agentlang dev:
+#
+#   Terminal 1:
+#   cd /path/to/knowledge-service
+#   export STORE_TYPE=sqlite
+#   export VECTOR_DB_TYPE=lancedb
+#   export LANCE_DB_PATH=./lance-data
+#   agentlang run src/core.al
+#
+#   Terminal 2:
+#   cd /path/to/your-app
+#   export KNOWLEDGE_SERVICE_URL=http://localhost:8080
+#   agentlang dev
+
+# =============================================================================
+# AI/ML Configuration (inherited by knowledge-service)
+# =============================================================================
+AGENTLANG_OPENAI_KEY=sk-your-openai-key-here
+
+# =============================================================================
+# Graph Database (inherited by knowledge-service)
+# =============================================================================
+GRAPH_DB_URI=bolt://localhost:7687
+GRAPH_DB_USER=neo4j
+GRAPH_DB_PASSWORD=password
+
+# =============================================================================
+# Development Configuration
+# =============================================================================
+# Set to true to enable debug logging
+DEBUG=false
+
+# Port for the agentlang-cli dev server
+AGENTLANG_PORT=4000

README.md

@@ -743,6 +743,93 @@ The CLI provides clear error messages for common issues:
 - **Validation Errors** - Semantic errors in Agentlang modules
 - **Runtime Errors** - Errors during program execution with stack traces
 
+## Environment Variables
+
+The CLI supports the following environment variables for configuration:
+
+### Knowledge Graph (Neo4j)
+
+Used by `agent studio` when knowledge graph features are enabled:
+
+| Variable            | Default                 | Description               |
+| ------------------- | ----------------------- | ------------------------- |
+| `GRAPH_DB_URI`      | `bolt://localhost:7687` | Neo4j Bolt connection URI |
+| `GRAPH_DB_USER`     | `neo4j`                 | Neo4j username            |
+| `GRAPH_DB_PASSWORD` | `password`              | Neo4j password            |
+
+Example:
+
+```bash
+export GRAPH_DB_URI=bolt://localhost:7687
+export GRAPH_DB_USER=neo4j
+export GRAPH_DB_PASSWORD=password
+agent studio
+```
+
+### AI/LLM Configuration
+
+| Variable                         | Default                  | Description                                     |
+| -------------------------------- | ------------------------ | ----------------------------------------------- |
+| `AGENTLANG_OPENAI_KEY`           | -                        | OpenAI API key (falls back to `OPENAI_API_KEY`) |
+| `AGENTLANG_LLM_MODEL`            | `gpt-4o-mini`            | Default LLM model for knowledge extraction      |
+| `AGENTLANG_EMBEDDING_MODEL`      | `text-embedding-3-small` | Embedding model for vector search               |
+| `AGENTLANG_EMBEDDING_DIMENSIONS` | `1536`                   | Embedding vector dimensions                     |
+
+### Knowledge Processing
+
+| Variable           | Default | Description                             |
+| ------------------ | ------- | --------------------------------------- |
+| `KG_CHUNK_SIZE`    | `1000`  | Text chunk size for document processing |
+| `KG_CHUNK_OVERLAP` | `200`   | Chunk overlap for document processing   |
+
+### Knowledge Service
+
+| Variable                | Default | Description                                              |
+| ----------------------- | ------- | -------------------------------------------------------- |
+| `KNOWLEDGE_SERVICE_URL` | -       | URL of external knowledge service (when not using local) |
+
+**New in v0.12.0:** Knowledge-service now runs as external service. See
+[Knowledge Service Setup](#knowledge-service-setup) below.
+
+### Knowledge Service Setup
+
+Starting with version 0.12.0, knowledge graph functionality is provided by an
+external **knowledge-service** that must be started separately.
+
+**Quick Start:**
+
+```bash
+# Terminal 1: Start knowledge-service
+cd /path/to/knowledge-service
+./start-local.sh
+# Service runs on http://localhost:8080
+
+# Terminal 2: Start your app with knowledge service URL
+cd /path/to/your-app
+export KNOWLEDGE_SERVICE_URL=http://localhost:8080
+agentlang dev
+```
+
+**Why External Service?**
+
+1. **Clean Separation**: Knowledge-service runs independently
+2. **Port Isolation**: No conflicts with your app's port
+3. **Better Debugging**: Separate logs and monitoring
+4. **Production Parity**: Same architecture as cloud deployment
+
+**Troubleshooting:**
+
+If knowledge-service is not running, you'll see a helpful error message with
+instructions on how to start it.
+
+**Deployment Options:**
+
+- **Local Dev**: `./start-local.sh` (SQLite + LanceDB)
+- **Docker**: `docker-compose up` (PostgreSQL + pgvector)
+- **Kubernetes**: `kubectl apply -f k8s/` (Production)
+
+---
+
 ## Development
 
 ### Building from Source

eslint.config.mjs

@@ -80,4 +80,27 @@ export default tseslint.config(
       'no-console': 'off',
     },
   },
+  // CLI source files - allow console for logging
+  {
+    files: ['src/**/*.ts'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  // Test files - disable type-aware rules since they're not in tsconfig
+  {
+    files: ['test/**/*.ts', '**/*.test.ts', '**/*.spec.ts'],
+    ...tseslint.configs.disableTypeChecked,
+  },
+  {
+    files: ['test/**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
 );