isA Orch

Unified code index and platform intelligence for the isA ecosystem.

Overview

isA Orch provides cross-project code intelligence — a single index spanning all 19 isA sub-projects with symbol resolution, call-graph analysis, full-text search, and semantic search. It is the shared intelligence substrate that skills and isa-vibe use for impact analysis, context detection, and TDD routing.

Quick Start

# Install
cd isA_Orch
pip install -e .
 
# Index all projects
isa-orch index
 
# Search across the platform
isa-orch search "ToolNode"
 
# Impact analysis
isa-orch impact "isa_agent_sdk.nodes.tool_node.ToolNode"
 
# Platform stats
isa-orch stats

Architecture

config/projects.yaml (19 projects)
         │
    ProjectRegistry
         │
      Indexer  ────→ PythonAST / TreeSitter / Classifier
         │
  PlatformIndex (SQLite + FTS5)
         │
  LocalEmbeddingIndex (optional, sentence-transformers)

Database: ~/Documents/Fun/isA/.isa/code_index.db

The architecture has three layers:

1. Registry — config/projects.yaml declares every sub-project with its path, language, and GitHub remote. The ProjectRegistry loads this file and resolves paths relative to the platform root.
2. Indexer — Walks each project, parses source files with the appropriate parser (Python ast for .py, tree-sitter for .ts/.js), extracts symbols (functions, classes, methods, variables), and records edges (calls, imports, inheritance).
3. Index — A single SQLite database with FTS5 full-text search and optional vector embeddings for semantic queries. All symbols carry a project tag enabling scoped and cross-project queries.

Core Features

Code Index (Tree-Sitter and AST Parsing)

The indexer extracts a complete symbol table from every source file in the platform. Each symbol record includes the qualified name, kind (function, class, method, variable), file path, line range, docstring, and project tag.

Python files are parsed with the built-in ast module, extracting:

• Functions and async functions (top-level and nested)
• Classes and their methods
• Module-level variables and constants
• Import relationships and call edges

TypeScript and JavaScript files are parsed with tree-sitter , extracting:

• Named and default exports
• Function declarations and arrow functions
• Class declarations with methods and properties
• Interface and type alias definitions
• Import statements and call expressions

The indexer is incremental — it checksums every file and only re-parses files that have changed since the last run, making re-indexing fast even across the full platform.

# Full index of all projects
isa-orch index
 
# Index a single project
isa-orch index --project isA_MCP
 
# Force full re-index (ignore checksums)
isa-orch index --full
 
# Index with semantic embeddings
isa-orch index --embeddings

Semantic Embedding Index

When the --embeddings flag is passed during indexing, isA Orch generates vector embeddings for every symbol using sentence-transformers . This enables semantic search — finding symbols by meaning rather than exact text match.

The embedding index uses a local model (no external API calls), so it works fully offline. Embeddings are stored alongside the FTS5 index in the same SQLite database.

Use cases for semantic search:

• Finding symbols related to a concept (“retry logic”, “error handling”, “authentication”)
• Discovering similar implementations across projects
• Locating code relevant to a natural-language description

# Index with embeddings (first time takes longer)
isa-orch index --embeddings
 
# Semantic search
isa-orch search "retry logic for failed tool calls" --semantic
 
# Combine semantic search with project scope
isa-orch search "authentication middleware" --semantic --project isA_Cloud

Cross-Project Symbol Search and Resolution

All symbols carry a project tag, enabling both scoped and platform-wide queries. The search engine supports three modes:

Full-text search (default) — Uses SQLite FTS5 for fast substring and token matching:

# Search across all projects
isa-orch search "tool_node"
 
# Search within a specific project
isa-orch search "tool_node" --project isA_Agent_SDK
 
# Filter by symbol kind
isa-orch search "ToolNode" --kind class
 
# JSON output for machine consumption
isa-orch search "ToolNode" --json

Semantic search — Uses vector embeddings for meaning-based queries:

isa-orch search "retry logic" --semantic

Symbol resolution — Given a short name, resolves it to all matching qualified names across the platform:

# Find all definitions of "ToolNode" across all projects
isa-orch search "ToolNode" --kind class
 
# Results show project, qualified name, file, and line range
# isA_Agent_SDK  isa_agent_sdk.nodes.tool_node.ToolNode  src/nodes/tool_node.py  42-128
# isA_Agent      isa_agent.tools.ToolNode                src/tools.py            15-67

Impact Analysis

The impact analysis engine traces the call graph of any symbol recursively across project boundaries. Given a symbol name, it returns every caller — direct and transitive — so you can understand the blast radius of a change before making it.

The algorithm uses a 3-pass edge resolution strategy:

1. Exact qualified name match — e.g., isa_agent_sdk.nodes.tool_node.ToolNode
2. Short name match within the same project — resolves unqualified references within a project
3. Short name match across all projects — catches cross-project usage via re-exports or dynamic imports

# Basic impact analysis
isa-orch impact "ToolNode"
 
# With depth control (default is unlimited)
isa-orch impact "ToolNode" --max-depth 3
 
# Scoped to a project
isa-orch impact "ToolNode" --project isA_Agent_SDK
 
# JSON output for programmatic use
isa-orch impact "isa_agent_sdk.nodes.tool_node.ToolNode" --json

Example output:

Impact analysis for: ToolNode (max-depth: 3)

Direct callers (depth 1):
  isA_Agent_SDK  AgentGraph.build()          src/graph.py:87
  isA_Agent      PlannerAgent._run_tools()   src/agents/planner.py:145

Transitive callers (depth 2):
  isA_Agent      AgentRunner.execute()       src/runner.py:34
  isA_Console    CLIHandler.handle_command()  src/cli/handler.ts:78

Transitive callers (depth 3):
  isA_Console    main()                       src/index.ts:12

Total: 5 callers across 3 projects

Platform Statistics

Get a high-level view of the index — total symbols, edges, projects, and language breakdown:

# Platform-wide stats
isa-orch stats
 
# Stats for a single project
isa-orch stats --project isA_Agent_SDK
 
# JSON output
isa-orch stats --json

Project Context Detection

Auto-detects language, framework, test runner, and infrastructure for any project directory:

isa-orch project-context ./isA_Agent_SDK

This is used internally by skills like /test and /codegen to adapt their output to the target project’s stack.

Test Scaffold

Creates the 5-layer test directory structure used by the isA TDD workflow:

isa-orch test-scaffold ./isA_Agent_SDK
# Creates: tests/{unit,component,integration,api,smoke}/

CLI Reference

All commands support --json for machine-readable output.

Project Registry

Projects are declared in config/projects.yaml. The registry currently tracks 19 sub-projects:

platform_root: ~/Documents/Fun/isA
 
projects:
  - name: isA_Agent_SDK
    description: Core agent framework with LangGraph nodes
    language: python
    github: xenoISA/isA_Agent_SDK
 
  - name: isA_MCP
    description: Tool server with 190+ tools
    language: python
    github: xenoISA/isA_MCP
 
  - name: isA_Console
    description: Console/UI interfaces
    language: typescript
    github: xenoISA/isA_Console
 
  # ... 16 more projects

Each entry specifies the project name, description, primary language, and GitHub remote. The registry is the single source of truth for which projects exist in the platform and is consumed by the indexer, search engine, and CLI.

How Skills Use isA Orch

isA Orch is not just a standalone tool — it provides the intelligence layer that other skills and pipelines depend on:

Tech Stack

Related

• Architecture — Platform overview
• Agent SDK — Core agent framework
• Cloud — Deployment infrastructure