# Getting Started Deploy Xctopus in your environment in three simple steps. --- ## 1. Installation ```bash git clone https://github.com/msancheza/xctopus-core.git cd xctopus-core/xctopus pip install -e . ``` **Tip**: Install `rich` for formatted console tables and progress bars: `pip install rich`. --- ## 2. Quick Start Choose your preferred way to interact with the framework: ### A. Interactive (Jupyter Notebook) The fastest way to visualize results. Open `notebooks/quickstart.ipynb`, point to your CSV, and run all cells. **Result**: Organic node creation + Fusion + Statistical summary. ### B. Programmatic (Python API) ```python from xctopus.main import initialize_components, process_dataset from xctopus.fusion import fuse_knowledge_nodes # 1. Initialize the 6-class engine repo, filter_b, orch = initialize_components() # 2. Process & Integrate Knowledge process_dataset(embeddings, repo, filter_b, orch) # 3. Consolidate (Fusion) fuse_knowledge_nodes(repo, orch) ``` --- ## 3. Understanding Results Xctopus provides real-time validation of your knowledge structure: | Metric | Target | Description | |--------|--------|-------------| | **Final KNs** | Variable | Total unique semantic clusters created. | | **Avg Mass** | > 1.0 | Density of information per node. | | **Avg Variance** | ~0.29 | Semantic purity (Lower = Higher Coherence). | --- ## Common Workflows ### New Dataset **Load → Embed → Process → Analyze** ### Incremental Learning Simply run `process_dataset()` again; Xctopus automatically loads existing nodes and integrates new data. ### Structural Analysis Use `repo.get_all_signatures()` to audit mass and variance. --- ## Best Practices ### ✅ Do - **Always use Fusion**: Consolidates nodes and reduces fragmentation. - **Target Variance**: Aim for ~0.29 for optimal semantic stability. ### ⚠️ Avoid - **Consistency**: Avoid changing `S_MIN` or `LAMBDA_FACTOR` mid-process to maintain structural integrity. --- ## Troubleshooting

Issue: "No module named 'xctopus'"

Make sure you're in the project directory and have installed: ```bash pip install -e . ```

Issue: "CUDA out of memory"

Use CPU mode or reduce batch size. Edit `src/xctopus/settings.py`: ```python DEVICE = "cpu" ```

Issue: "Too many Knowledge Nodes"

Increase similarity threshold or run fusion: ```python S_MIN = 0.75 # Stricter threshold ```

---