Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .docs/summary-CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,17 @@ Provides comprehensive guidance to Claude Code (claude.ai/code) when working wit
- **Knowledge Graph System**: Thesaurus format, automata construction, rolegraph management
- **AI Integration**: OpenRouter, Ollama support with LLM client abstraction

## Recent Updates
## Recent Updates (v1.0.0 Release)
- **Multi-Language Package Ecosystem**: Added comprehensive Rust, Node.js, Python package information
- **Package Manager Support**: Enhanced with Bun optimization for Node.js ecosystem
- **CI/CD Infrastructure**: Updated with self-hosted runners and 1Password integration
- **Grep.app Integration**: Added search across 500,000+ GitHub repositories
- **MCP Server**: Complete Model Context Protocol implementation for AI integration
- **Binary Update**: terraphim-tui → terraphim-agent with updated references
- **Performance Metrics**: Added comprehensive benchmarks and optimization details
- **Publishing Documentation**: Complete guides for multi-language package publishing

## Legacy Updates
- Added workspace structure section
- Expanded crate documentation (agent systems, haystacks)
- Added TUI build variations and feature flags
Expand Down
26 changes: 24 additions & 2 deletions .docs/summary-README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,38 @@ Main project documentation for Terraphim AI, a privacy-first AI assistant that o
- **Rolegraph**: Knowledge graph using Aho-Corasick automata for ranking

## Installation Options

### 🎉 v1.0.0 Multi-Language Packages

**🦀 Rust (crates.io)**:
```bash
cargo install terraphim_agent
terraphim-agent --help
```

**📦 Node.js (npm)**:
```bash
npm install @terraphim/autocomplete
# or with Bun
bun add @terraphim/autocomplete
```

**🐍 Python (PyPI)**:
```bash
pip install terraphim-automata
```

### Traditional Installation
- **Docker**: `docker run ghcr.io/terraphim/terraphim-server:latest`
- **Homebrew**: `brew install terraphim/terraphim-ai/terraphim-ai`
- **Quick Install**: `curl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/release/v0.2.3/install.sh | bash`
- **Development**: `git clone && cargo run`

## Development Setup
1. Clone repository
2. Install pre-commit hooks: `./scripts/install-hooks.sh`
3. Start backend: `cargo run`
4. Start frontend: `cd desktop && yarn run dev` (web) or `yarn run tauri dev` (desktop)
5. TUI: `cargo build -p terraphim_tui --features repl-full --release`
5. TUI: `cargo build -p terraphim_tui --features repl-full --release && ./target/release/terraphim-agent`

## Important Details
- Storage backends: Local by default (memory, dashmap, sqlite, redb); optional AWS S3 for cloud
Expand Down
2 changes: 2 additions & 0 deletions .docs/summary-TESTING_SCRIPTS_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
## Purpose
Comprehensive documentation for testing scripts used in Novel editor autocomplete integration with Terraphim's knowledge graph system. Provides automated testing workflows and service management.

**Updated for v1.0.0**: Now includes testing for multi-language packages (Rust, Node.js, Python) and comprehensive validation of autocomplete functionality across all platforms.

## Key Scripts
- **quick-start-autocomplete.sh**: Interactive menu with preset configurations (full, mcp, dev, test, status, stop)
- **start-autocomplete-test.sh**: Main testing script with full control over services and configuration
Expand Down
22 changes: 22 additions & 0 deletions .docs/summary-lessons-learned.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,28 @@ Captures critical technical insights, development patterns, and lessons from Ter
- **Categories**: Prompt injection, command injection, memory safety, network validation
- **Coverage**: 99 comprehensive tests across multiple attack vectors

**Pattern 6: Multi-Language Package Publishing Strategy**
- **Context**: v1.0.0 release with Rust, Node.js, Python packages
- **Learning**: Platform-specific bindings require different approaches but unified API design
- **Rust (crates.io)**: Native publishing with comprehensive documentation
- **Node.js (npm)**: NAPI bindings for zero-overhead native performance
- **Python (PyPI)**: PyO3 bindings for maximum speed with universal wheels
- **Key Success**: Consistent API design across all languages while leveraging platform strengths

**Pattern 7: Comprehensive Multi-Package-Manager Support**
- **Context**: Node.js ecosystem evolution beyond npm
- **Learning**: Support multiple package managers for maximum reach
- **Implementation**: npm + Bun optimization with performance benchmarking
- **Benefits**: Faster installation (Bun), broader compatibility (npm), developer choice
- **Testing**: Automated testing across all supported package managers

**Pattern 8: CI/CD Infrastructure Migration**
- **Context**: Earthly to GitHub Actions migration for self-hosted runners
- **Learning**: Gradual migration with parallel systems reduces risk
- **Approach**: Maintain Earthly while building GitHub Actions, then switch
- **Key Benefits**: Self-hosted runners, 1Password integration, faster builds
- **Security**: OIDC authentication for package publishing with secure token management

## Technical Insights

**UI Development**:
Expand Down
21 changes: 21 additions & 0 deletions .docs/summary-memories.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,27 @@ Comprehensive development history and progress tracking for the Terraphim AI pro

## Critical Sections

### v1.0.0 Major Release Achievements (2025-11-16)

**Multi-Language Package Ecosystem (COMPLETE ✅)**:
- **Rust terraphim_agent**: Published to crates.io with CLI/TUI interface
- **Node.js @terraphim/autocomplete**: Published to npm with NAPI bindings and Bun support
- **Python terraphim-automata**: Published to PyPI with PyO3 bindings
- **10 Core Rust Crates**: All successfully published to crates.io
- **Comprehensive CI/CD**: Self-hosted runners with 1Password integration

**Enhanced Search Integration (COMPLETE ✅)**:
- **Grep.app Integration**: Search across 500,000+ GitHub repositories
- **Advanced Filtering**: Language, repository, and path-based filtering
- **MCP Server**: Complete Model Context Protocol implementation
- **Claude Code Hooks**: Automated workflows and integration templates

**Documentation & Release (COMPLETE ✅)**:
- **Comprehensive v1.0.0 Documentation**: README, release notes, API docs
- **Multi-Language Installation Guides**: Step-by-step instructions
- **GitHub Release**: Complete with changelog and installation instructions
- **terraphim-agent Binary**: Successfully updated from terraphim-tui references

### Recent Major Achievements (2025-10-08)

**TruthForge Phase 5 UI Development (COMPLETE ✅)**:
Expand Down
41 changes: 25 additions & 16 deletions .docs/summary-scratchpad.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,31 @@ Active task management and current work tracking for Terraphim AI development. D
- **System Status**: Current health of various components
- **Phase Planning**: Upcoming work and priorities

## Current Status (Latest Update: October 18, 2025)

**✅ Phase 1 Security Testing Complete**
- 43 security tests implemented (19 in terraphim-ai, 24 in firecracker-rust)
- All critical vulnerabilities fixed: prompt injection, command injection, unsafe memory, network injection
- 28 tests passing on bigbox validation
- Risk level reduced from HIGH to MEDIUM

**🔄 Phase 2 Security Bypass Testing - Ready to Start**
- **Objective**: Test effectiveness of implemented security controls
- **Timeline**: October 18-25, 2025
- **Focus Areas**:
- Advanced prompt injection bypass (encoding, context manipulation)
- Command injection bypass (shell metacharacter evasion)
- Memory safety bypass (buffer overflow attempts)
- Network security bypass (interface name spoofing)
## Current Status (Latest Update: November 16, 2025)

**🎉 v1.0.0 MAJOR RELEASE COMPLETE**
- Multi-language package ecosystem successfully released
- All 10 core Rust crates published to crates.io
- Node.js @terraphim/autocomplete published to npm with Bun support
- Python terraphim-automata published to PyPI
- Comprehensive documentation and GitHub release completed
- terraphim-tui successfully renamed to terraphim-agent across all references

**✅ v1.0.0 Release Achievements**
- **Multi-Language Support**: Rust, Node.js, Python packages available
- **Enhanced Search**: Grep.app integration (500K+ GitHub repos)
- **AI Integration**: Complete MCP server and Claude Code hooks
- **Infrastructure**: Self-hosted CI/CD runners with 1Password integration
- **Performance**: Sub-2s startup, sub-millisecond search, optimized binaries

**🔄 Next Development Phase - Ready to Start**
- **Objective**: Build upon v1.0.0 foundation with advanced features
- **Timeline**: November 2025 onward
- **Potential Focus Areas**:
- Enhanced WebAssembly support
- Plugin architecture for extensions
- Advanced AI model integrations
- Performance optimizations and benchmarks

## Critical Sections

Expand Down
89 changes: 87 additions & 2 deletions .docs/summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

Terraphim AI is a privacy-first, locally-running AI assistant featuring multi-agent systems, knowledge graph intelligence, and secure code execution in Firecracker microVMs. The project combines Rust-based backend services with vanilla JavaScript frontends, emphasizing security, performance, and production-ready architecture.

**Current Status**: Production-ready with active development on advanced features
**Primary Technologies**: Rust (async/tokio), Svelte/Vanilla JS, Firecracker VMs, OpenRouter/Ollama LLMs
**Current Status**: v1.0.0 RELEASED - Production-ready with comprehensive multi-language package ecosystem
**Primary Technologies**: Rust (async/tokio), Svelte/Vanilla JS, Firecracker VMs, OpenRouter/Ollama LLMs, NAPI, PyO3
**Test Coverage**: 99+ comprehensive tests with 59 passing in main workspace

## System Architecture
Expand Down Expand Up @@ -245,6 +245,91 @@ cd desktop && yarn run check
3. **Haystack Integration** (4 crates): atomic_client, clickup_client, query_rs_client, persistence
4. **Infrastructure**: settings, tui, onepassword_cli, markdown_parser

## 🎉 v1.0.0 Major Release Achievements

### Multi-Language Package Ecosystem ✅

**🦀 Rust - terraphim_agent (crates.io)**:
- Complete CLI/TUI interface with REPL functionality
- Sub-2 second startup times and 10MB optimized binary
- Installation: `cargo install terraphim_agent`
- Published with comprehensive documentation and examples

**📦 Node.js - @terraphim/autocomplete (npm)**:
- Native NAPI bindings with zero overhead
- High-performance autocomplete engine using Aho-Corasick automata
- Knowledge graph connectivity analysis and semantic search
- Multi-platform support (Linux, macOS, Windows, ARM64)
- Bun package manager optimization included
- Installation: `npm install @terraphim/autocomplete`

**🐍 Python - terraphim-automata (PyPI)**:
- PyO3 bindings for maximum performance
- Cross-platform wheels for all major platforms
- Type hints and comprehensive documentation
- Installation: `pip install terraphim-automata`

### Enhanced Search Capabilities ✅

**Grep.app Integration**:
- Search across 500,000+ public GitHub repositories
- Advanced filtering by language, repository, and path
- Rate limiting and graceful error handling

**Semantic Search Enhancement**:
- Knowledge graph-powered semantic understanding
- Context-aware relevance through graph connectivity
- Multi-source integration (personal, team, public)

### AI Integration & Automation ✅

**MCP Server Implementation**:
- Complete Model Context Protocol server for AI tool integration
- All autocomplete and knowledge graph functions exposed as MCP tools
- Transport support: stdio, SSE/HTTP with OAuth authentication

**Claude Code Hooks**:
- Automated workflows for seamless Claude Code integration
- Template system for code analysis and evaluation
- Quality assurance frameworks and comprehensive testing

### Infrastructure Improvements ✅

**CI/CD Migration**:
- Complete migration from Earthly to GitHub Actions + Docker Buildx
- Self-hosted runners for optimized build infrastructure
- 1Password integration for secure token management
- Multi-platform builds (Linux, macOS, Windows, ARM64)

**10 Core Rust Crates Published**:
1. terraphim_agent - Main CLI/TUI interface
2. terraphim_automata - Text processing and autocomplete
3. terraphim_rolegraph - Knowledge graph implementation
4. terraphim_service - Main service layer
5. terraphim_middleware - Haystack indexing and search
6. terraphim_config - Configuration management
7. terraphim_persistence - Storage abstraction
8. terraphim_types - Shared type definitions
9. terraphim_settings - Device and server settings
10. terraphim_mcp_server - MCP server implementation

### Performance Metrics ✅

**Autocomplete Engine**:
- Index Size: ~749 bytes for full engineering thesaurus
- Search Speed: Sub-millisecond prefix search
- Memory Efficiency: Compact serialized data structures

**Knowledge Graph**:
- Graph Size: ~856 bytes for complete role graphs
- Connectivity Analysis: Instant path validation
- Query Performance: Optimized graph traversal algorithms

**Native Binaries**:
- Binary Size: ~10MB (production optimized)
- Startup Time: Sub-2 second CLI startup
- Cross-Platform: Native performance on all supported platforms

## Development Patterns and Best Practices

### Learned Patterns (From lessons-learned.md)
Expand Down
11 changes: 11 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Environment Variables Example
# Copy this file to .env and fill in the actual values

# crates.io token for publishing Rust crates
# Get this from 1Password: op read "op://TerraphimPlatform/crates.io.token/token" # pragma: allowlist secret
CARGO_REGISTRY_TOKEN=

# Optional: Local development overrides
# TERRAPHIM_CONFIG=./terraphim_engineer_config.json
# TERRAPHIM_DATA_DIR=./data
# LOG_LEVEL=debug
10 changes: 5 additions & 5 deletions .env.tauri-release
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
# These references point to secrets stored in 1Password
# Use with: op run --env-file=.env.tauri-release -- <command>

# Tauri signing keys for auto-update (stored in TerraphimPlatform vault)
TAURI_PRIVATE_KEY="op://6fsizn2h5rrs5mp3e4phudjab4/3k2d5ycxeagdazexivgomi2gpy/TAURI_PRIVATE_KEY"
TAURI_KEY_PASSWORD="op://6fsizn2h5rrs5mp3e4phudjab4/3k2d5ycxeagdazexivgomi2gpy/TAURI_KEY_PASSWORD"
# Tauri signing keys for auto-update (stored in TerraphimPlatform vault) # pragma: allowlist secret
TAURI_PRIVATE_KEY="op://6fsizn2h5rrs5mp3e4phudjab4/3k2d5ycxeagdazexivgomi2gpy/TAURI_PRIVATE_KEY" # pragma: allowlist secret
TAURI_KEY_PASSWORD="op://6fsizn2h5rrs5mp3e4phudjab4/3k2d5ycxeagdazexivgomi2gpy/TAURI_KEY_PASSWORD" # pragma: allowlist secret

# GitHub release token
GITHUB_TOKEN="op://Terraphim-Deployment/GitHub Release Token/GITHUB_TOKEN"
# GitHub release token # pragma: allowlist secret
GITHUB_TOKEN="op://Terraphim-Deployment/GitHub Release Token/GITHUB_TOKEN" # pragma: allowlist secret

# Build configuration
TAURI_SIGNING_ENABLED="true"
Expand Down
2 changes: 1 addition & 1 deletion .env.test
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
TERRAPHIM_SERVER_PORT=8000
ATOMIC_SERVER_URL=http://localhost:9883
ATOMIC_SERVER_SECRET=test-secret-key
ATOMIC_SERVER_SECRET=test-secret-key # pragma: allowlist secret
MCP_SERVER_URL=http://localhost:8001
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2:3b
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci-optimized.yml
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ jobs:
# Test binaries
./target/${{ matrix.target }}/release/terraphim_server --version
./target/${{ matrix.target }}/release/terraphim_mcp_server --version
./target/${{ matrix.target }}/release/terraphim-tui --version
./target/${{ matrix.target }}/release/terraphim-agent --version
"

- name: Create .deb package
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ env:
jobs:
build:
name: Build Documentation
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim]
steps:
- name: Checkout repository
uses: actions/checkout@v4
Expand Down Expand Up @@ -65,7 +65,7 @@ jobs:
name: Deploy Preview
needs: build
if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'preview')
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim]
permissions:
contents: read
deployments: write
Expand Down Expand Up @@ -126,7 +126,7 @@ jobs:
name: Deploy Production
needs: build
if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'production')
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim]
permissions:
contents: read
deployments: write
Expand Down Expand Up @@ -178,7 +178,7 @@ jobs:
purge-cache:
name: Purge CDN Cache
needs: deploy-production
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim]
permissions:
id-token: write
steps:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/docker-multiarch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ env:

jobs:
build-and-push:
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim, docker]
strategy:
matrix:
ubuntu-version: ${{ fromJSON(inputs.ubuntu-versions) }}
Expand Down Expand Up @@ -138,7 +138,7 @@ jobs:

build-summary:
needs: build-and-push
runs-on: ubuntu-latest
runs-on: [self-hosted, Linux, terraphim]
if: always()

steps:
Expand Down
Loading
Loading