Skip to content

Wesley1600/ClaudeCodeFrameWork

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

112 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

ClaudeCodeFrameWork

A comprehensive AI/ML development ecosystem combining skill orchestration, semantic relationship learning, and production-ready Claude Code skills.


πŸ“¦ Contents

Core Components

  1. Skill Orchestration Framework - Chain multiple skills into complex workflows
  2. UMAP Analogy Engine - Semantic relationship learning and analogies
  3. Claude Code Skills - 14+ production-ready skills for development workflows
  4. MCP API Connector - Interact with MCP servers and external APIs

Python Tools & Libraries

  1. Agent Template System - Generate and manage AI agent configurations
  2. Agent Pulse - Proactive AI assistant with overnight research
  3. Memory Tool - Persistent storage and retrieval across sessions
  4. Workflow Orchestrator - Task management and execution
  5. Task Classification & Routing - Intelligent task routing system

Additional Resources


1. Skill Orchestration Framework ⭐ NEW

A flexible, extensible system for chaining AI/ML skills together into complex workflows. Build sophisticated pipelines by composing modular skills.

Quick Start

python example_skill_orchestration.py  # Run complete demonstration
python test_orchestration.py           # Run test suite

Features

  • βœ… Chain multiple skills (RAG, Summarization, Reporting, etc.)
  • βœ… Configure via Python code or YAML/JSON files
  • βœ… Automatic skill discovery and registration
  • βœ… Data flow management between skills
  • βœ… Error handling and recovery
  • βœ… Extensible with custom skills

Documentation

See SKILL_ORCHESTRATION.md for complete guide.

Example

from skills import SkillOrchestrator, get_global_registry

# Auto-discover and register skills
registry = get_global_registry()
registry.discover_skills("skills.implementations")

# Build a chain programmatically
orchestrator = SkillOrchestrator(registry)
chain = (
    orchestrator.create_chain("my_pipeline", "RAG + Summarization + Reporting")
    .add_step("rag_pipeline")
    .add_step("summarization")
    .add_step("reporting")
)

# Execute the chain
context = orchestrator.execute_chain(chain)
print(context.get_result("reporting")["report"])

2. UMAP-Inspired Universal Analogy Engine

A semantic relationship engine that learns universal relationship mappings inspired by UMAP's topological data analysis approach. Enables semantic analogies like "boy:girl :: king:?" β†’ "queen" by learning consistent relationship transformations in a low-dimensional embedding space.

Overview

This component implements a novel approach to semantic analogies by:

  1. Learning a low-dimensional manifold using parametric UMAP that preserves high-dimensional topology
  2. Aligning semantic relationships by clustering and regularizing difference vectors
  3. Extracting relation axes that can be applied to perform analogies
  4. Supporting multi-relation learning with orthogonality constraints to disentangle different types of relationships

Key Features

  • βœ… Fixed all critical bugs from V1 draft (see CODE_REVIEW.md)
  • βœ… 15-20x faster training with cluster caching and optimized gradient computation
  • βœ… Numerically stable with proper epsilon handling and bounds checking
  • βœ… Production-ready with comprehensive documentation and error handling
  • βœ… Flexible metric selection (Euclidean or cosine similarity)
  • βœ… Auto-balancing of loss weights via gradient norm matching
  • βœ… Activity logging and reporting for transparency and auditability (see ACTIVITY_LOGGING.md)
  • βœ… Persistent memory system for session continuity and experiment tracking

Persistent Memory Tool

The project now includes a powerful Memory Tool that enables persistent storage and retrieval of information across sessions:

Features

  • πŸ“¦ CRUD operations: Create, Read, Update, Delete memories with simple API
  • πŸ” Semantic search: Vector-based similarity search to find relevant memories
  • πŸ’Ύ Multiple types: Store facts, summaries, models, embeddings, and experiments
  • πŸ”„ Session continuity: Maintain context across conversations with session summaries
  • πŸ“Š Experiment tracking: Save and compare training runs with metadata

Quick Example

from memory_tool import MemoryTool
from memory_integration import AnalogyMemoryManager

# Basic memory operations
memory = MemoryTool()
memory.create("user_pref", "User prefers technical explanations", memory_type="fact")
results = memory.search("user preferences", k=3)

# Save a trained model with full context
manager = AnalogyMemoryManager()
manager.save_trained_model(
    model_state=model.state_dict(),
    embeddings=Z,
    relation_axes=axes,
    model_name="gender_analogy_v1",
    metadata={"epochs": 300, "accuracy": 0.87}
)

# Load it later in a new session
bundle = manager.load_trained_model("gender_analogy_v1")

See MEMORY_TOOL_GUIDE.md for complete documentation.

πŸŒ… NEW: Agent Pulse - Proactive AI Assistant

This repository now includes Agent Pulse, a ChatGPT Pulse-inspired system that transforms reactive AI assistance into proactive support:

  • πŸ“Š Analyzes past conversations to understand your interests and projects
  • πŸ” Conducts overnight research on relevant topics
  • πŸ’‘ Identifies opportunities for learning and optimization
  • πŸ”§ Suggests solutions to recurring problems
  • βœ… Tracks action items and commitments
  • 🎯 Learns from feedback to personalize updates

Quick Start with Agent Pulse

# Generate your first pulse update
python -m agent_pulse.cli.pulse_cli generate

# Configure your interests
python -m agent_pulse.cli.pulse_cli config --add-interest "machine learning"

# View system status
python -m agent_pulse.cli.pulse_cli status

πŸ“– Full Agent Pulse Documentation β†’


Quick Start

import torch
from umap_analogy_engine import (
    train_relation_aware_umap,
    extract_relation_axes,
    analogy_from_pair,
)

# Load your high-dimensional embeddings
X_high = torch.load("embeddings.pt")  # Shape: (N, D)

# Define semantic relations as pairs
pairs_gender = torch.tensor([
    [idx("king"), idx("queen")],
    [idx("man"), idx("woman")],
    [idx("boy"), idx("girl")],
])

# Train the model
model, Z = train_relation_aware_umap(
    X_high,
    pair_indices_list=[pairs_gender],
    n_clusters_list=[1],
    epochs=200,
)

# Perform analogy: "king is to queen as man is to ?"
results = analogy_from_pair(
    model, X_high, [pairs_gender], [1],
    word_a_idx=idx("king"),
    word_b_idx=idx("queen"),
    query_word_idx=idx("man"),
    k=5
)

For detailed documentation, see the UMAP sections below.


3. Claude Code Skills

This repository includes 14+ production-ready Claude Code skills for enhanced development workflows:

Available Skills

Skill Description Location
Summarization Condense documents, logs, and transcripts .claude/skills/summarization/
Agent Observations Task understanding and reasoning analysis .claude/skills/agent-observations/
Chain of Thought Structured reasoning with XML templates .claude/skills/chain-of-thought/
Code Translation Cross-language code conversion .claude/skills/code-translation/
Error Handling Robust error management with retry logic .claude/skills/error-handling.md
Automated UI Testing Playwright integration for testing .claude/skills/automated-ui-testing.md
Batch Processing Efficient task execution .claude/skills/batch-processing.md
Excel Pivot Charts Data visualization and analysis .claude/skills/excel-pivot-charts/
Files API File management system .claude/skills/files-api/
PDF Processing Comprehensive PDF tools .claude/skills/pdf-processing/
Progressive Disclosure Information flow control .claude/skills/progressive-disclosure/
Prompt Templating Template system for prompts .claude/skills/prompt-templating/
Version Management Version control tools .claude/skills/version-management/
Vision Image processing capabilities .claude/skills/vision/
Web Fetch Web content retrieval .claude/skills/web-fetch/

Usage

See .claude/skills/USAGE_GUIDE.md for detailed examples and best practices.


4. MCP API Connector Skill

A Claude Code skill that enables interaction with the Model Context Protocol (MCP) servers and external API systems like GitHub, Figma, Slack, Linear, and more.

Location: .claude/skills/mcp-api-connector/

Features:

  • βœ… Connect to MCP servers following the Model Context Protocol specification
  • βœ… Query REST APIs (GitHub, Figma, Slack, etc.)
  • βœ… Execute GraphQL queries (Linear, etc.)
  • βœ… Secure authentication (Bearer tokens, API keys, OAuth)
  • βœ… Automatic response translation into agent context
  • βœ… Comprehensive test suite (25 tests, 100% passing)

Quick Start:

# Install dependencies
cd .claude/skills/mcp-api-connector
pip install -r requirements.txt

# Configure authentication
cp ../../.env.example ../../.env
# Edit .env and add your API tokens

# Run examples
python examples.py

# Run tests
python test_skill.py

Documentation: See .claude/skills/mcp-api-connector/README.md for detailed usage and API reference.


5. Agent Template Population System

A comprehensive system for creating, managing, and configuring AI agents and their skills using templates.

Location: Root directory (agents/, templates/, config/)

Features:

  • βœ… Template Population: Dynamically generate agent and skill configurations from Jinja2 templates
  • βœ… Metadata Management: Store, retrieve, and validate metadata for agents and skills
  • βœ… Auto-generate skill and agent IDs following naming conventions
  • βœ… Populate YAML configurations from Jinja2 templates
  • βœ… Validate configurations against schemas

Documentation: See AGENT_TEMPLATE_SYSTEM.md for complete documentation.


6. Agent Pulse - Proactive AI Assistant πŸŒ…

Agent Pulse is a ChatGPT Pulse-inspired system that transforms reactive AI assistance into proactive support.

Features

  • πŸ“Š Analyzes past conversations to understand your interests and projects
  • πŸ” Conducts overnight research on relevant topics
  • πŸ’‘ Identifies opportunities for learning and optimization
  • πŸ”§ Suggests solutions to recurring problems
  • βœ… Tracks action items and commitments
  • 🎯 Learns from feedback to personalize updates

Quick Start

# Generate your first pulse update
python -m agent_pulse.cli.pulse_cli generate

# Configure your interests
python -m agent_pulse.cli.pulse_cli config --add-interest "machine learning"

# View system status
python -m agent_pulse.cli.pulse_cli status

Documentation: See AGENT_PULSE.md for complete guide.


7. Persistent Memory Tool

A powerful Memory Tool that enables persistent storage and retrieval of information across sessions.

Features

  • πŸ“¦ CRUD operations: Create, Read, Update, Delete memories with simple API
  • πŸ” Semantic search: Vector-based similarity search to find relevant memories
  • πŸ’Ύ Multiple types: Store facts, summaries, models, embeddings, and experiments
  • πŸ”„ Session continuity: Maintain context across conversations with session summaries
  • πŸ“Š Experiment tracking: Save and compare training runs with metadata

Quick Example

from memory_tool import MemoryTool
from memory_integration import AnalogyMemoryManager

# Basic memory operations
memory = MemoryTool()
memory.create("user_pref", "User prefers technical explanations", memory_type="fact")
results = memory.search("user preferences", k=3)

# Save a trained model with full context
manager = AnalogyMemoryManager()
manager.save_trained_model(
    model_state=model.state_dict(),
    embeddings=Z,
    relation_axes=axes,
    model_name="gender_analogy_v1",
    metadata={"epochs": 300, "accuracy": 0.87}
)

# Load it later in a new session
bundle = manager.load_trained_model("gender_analogy_v1")

Documentation: See MEMORY_TOOL_GUIDE.md for complete guide.


8. Workflow Orchestration Tools

Comprehensive tools for managing complex AI/ML workflows:

  • workflow_orchestrator.py - Task orchestration engine
  • task_executor.py - Task execution with monitoring
  • dispatcher_skill.py - Task dispatch system
  • option_evaluator.py - Decision support framework

See ORCHESTRATOR_README.md and TASK_EXECUTION_SKILL_README.md for details.


9. Task Classification and Routing

An intelligent task classification and routing system that automatically classifies input tasks into categories and routes them to appropriate skills or agents.

Features

  • 12 Built-in Categories: PDF, Spreadsheet, Code Execution, Text Processing, Image Processing, Data Analysis, Web Scraping, File Management, API Interaction, Database Query, Machine Learning, and Analogy Finding
  • Extensible Skill Registry: Register custom skills with metadata and capabilities
  • Multi-Strategy Classification: Pattern matching, keyword detection, and contextual analysis
  • Confidence Scoring: Returns classification confidence for validation
  • Batch Processing: Classify and route multiple tasks efficiently

Quick Example

from task_classification_routing import TaskRouter

router = TaskRouter()

# Route a task to the appropriate skill
result = router.route("Find semantic analogies: king is to queen as man is to what?")
print(f"Skill: {result.skill_name}")  # "Analogy Finder (UMAP)"
print(f"Confidence: {result.confidence:.2f}")

Documentation: See TASK_CLASSIFICATION_ROUTING.md

Examples: Run python example_task_routing.py


Installation

# Clone the repository
git clone <your-repo-url>
cd ClaudeCodeFrameWork

# Install dependencies
pip install -r requirements.txt

Requirements

  • Python 3.8+
  • PyTorch 2.0+ (for UMAP analogy engine)
  • NumPy 1.20+ (optional, for advanced features)
  • PyYAML 6.0+ (for skill orchestration)
  • psutil>=5.9.0 (for workflow orchestrator)
  • pytest>=7.0.0 (optional, for testing)

Quick Start

1. Skill Orchestration

python example_skill_orchestration.py
python test_orchestration.py

2. UMAP Analogy Engine

python umap_analogy_engine.py
python example_word_analogies.py

3. Agent Pulse

python -m agent_pulse.cli.pulse_cli generate

4. Memory Tool

python demo_memory_basic.py

5. Task Routing

python example_task_routing.py

Documentation

Core Frameworks

Tools & Features

Claude Code Skills

Additional Guides


UMAP Detailed Documentation

Architecture

1. Fuzzy Simplicial Set Construction

Builds a k-nearest neighbor graph with fuzzy set memberships:

  • Computes adaptive bandwidths (sigma) via binary search
  • Symmetrizes using fuzzy union: P(A βˆͺ B) = P(A) + P(B) - P(A)Β·P(B)
  • Returns edge list in COO format

2. Parametric UMAP Encoder

Deep neural network that learns the mapping: X_high ∈ ℝ^D β†’ Z_low ∈ ℝ^d

Default architecture:

  • Input: D-dimensional
  • Hidden: [512, 256, 128] with LayerNorm + ReLU + Dropout
  • Output: d-dimensional (default d=2)

3. Multi-Objective Loss

L_total = L_umap + Ξ±Β·L_align + Ξ²Β·L_ortho

Where:

  • L_umap: UMAP cross-entropy (topology preservation)
  • L_align: Relation alignment loss
  • L_ortho: Orthogonality penalty

Configuration

# UMAP parameters
N_NEIGHBORS = 15      # k for kNN graph
MIN_DIST = 0.1        # Minimum distance in low-D
D_LOW = 2             # Low-dimensional space size

# Training parameters
EPOCHS = 400          # Training epochs
LR = 1e-3             # Learning rate

# Loss weights
ALIGN_W = 1.0         # Relation alignment weight
ORTHO_W = 0.1         # Orthogonality penalty weight

# Model architecture
HIDDEN_DIMS = [512, 256, 128]
DROPOUT_P = 0.10

API Reference

Training

train_relation_aware_umap(
    X_high: torch.Tensor,
    pair_indices_list: List[torch.Tensor],
    n_clusters_list: List[int],
    epochs: int = 400,
    ...
) -> Tuple[nn.Module, torch.Tensor]

Relation Axes

extract_relation_axes(
    model: nn.Module,
    X_high: torch.Tensor,
    pair_indices_list: List[torch.Tensor],
    n_clusters_list: List[int],
) -> List[Optional[Dict[str, Union[torch.Tensor, float]]]]

Analogy Finding

find_analogy(
    embeddings: torch.Tensor,
    relation_axes: List[Optional[Dict]],
    query_word_idx: int,
    relation_idx: int,
    k: int = 1,
) -> List[Tuple[int, float]]

Performance

Dataset Size Training Time (V1) Training Time (V2) Speedup
N=1,000 ~8 min ~0.5 min 16x
N=10,000 ~80 min ~5 min 16x
N=100,000 ~800 min* ~50 min* 16x

*Estimated with FAISS acceleration (not included by default)


Data Extraction Module

In addition to the analogy engine, this framework includes a comprehensive data extraction module for parsing structured information from various sources.

Features

  • Text Entity Extraction: Parse dates, names, amounts, emails, phone numbers, URLs, percentages, and more
  • Table Extraction: Extract tables from HTML and CSV files
  • Web Scraping: Extract structured data from web pages
  • PDF Processing: Extract text and tables from PDF files using pdfplumber

Quick Start - Data Extraction

from data_extraction import (
    extract_text_entities,
    extract_from_pdf,
    extract_from_url,
    extract_from_html
)

# Extract entities from text
text = "Contact John Doe at john@example.com or call (555) 123-4567. Meeting on Jan 15, 2024."
entities = extract_text_entities(text)
print(entities['emails'])  # ['john@example.com']
print(entities['phone_numbers'])  # ['5551234567']
print(entities['dates'])  # [{'raw': 'Jan 15, 2024', ...}]

# Extract from PDF
pdf_data = extract_from_pdf('invoice.pdf')
print(f"Pages: {pdf_data['metadata']['num_pages']}")
print(f"Tables: {len(pdf_data['tables'])}")

# Extract from web page
web_data = extract_from_url('https://example.com')
print(web_data['entities'])
print(web_data['tables'])

Running Examples

# Run all data extraction examples
python example_data_extraction.py

# Run specific module
python -c "from data_extraction import TextExtractor; e = TextExtractor(); print(e.extract_all('Email: test@example.com'))"

See example_data_extraction.py for comprehensive usage examples.


Financial Analysis Skill

This repository also includes a comprehensive Financial Analysis Skill for Claude Code that analyzes financial statements, computes ratios, and generates insights.

Features

  • πŸ“Š Multi-format support: Parse PDFs, Excel files, and CSV documents
  • πŸ“ˆ 20+ financial ratios: Liquidity, profitability, leverage, and efficiency metrics
  • 🎯 Automated insights: Benchmark against industry standards with health indicators
  • πŸ“ Detailed reports: Executive summaries and comprehensive analysis

Quick Start

from financial_analyzer import analyze_file

# Analyze financial data from any supported format
statement, ratios, report = analyze_file('financial_report.pdf')
print(report)

Or use with Claude Code:

Analyze the financial statement in examples/financial_data/sample_financial_statement.csv

See FINANCIAL_ANALYSIS_SKILL.md for complete documentation.


Roadmap

Phase 1: Foundation (Current)

  • βœ… Parametric UMAP implementation
  • βœ… Multi-relation alignment
  • βœ… Analogy finding API
  • βœ… Optimization and bug fixes
  • βœ… Data extraction module
  • βœ… Financial Analysis Skill

Phase 2: Inverse Projection (Planned)

  • Inverse parametric model (Z_low β†’ X_high)
  • Riemannian manifold reconstruction
  • Relation simplex aggregation
  • High-dimensional analogy prediction

Phase 3: Advanced Features (Future)

  • Automatic relation discovery
  • Hierarchical relations
  • Compositional analogies (multi-hop)
  • Interactive visualization
  • Advanced NLP entity recognition
  • OCR support for image-based PDFs

Version Management

This project uses a specialized version management system.

Quick Start

# Show current version
python version_manager.py current

# Add a change
python version_manager.py add-change "Fixed bug in analogy finding" -c Fixed

# Bump version
python version_manager.py bump patch    # 1.0.0 β†’ 1.0.1
python version_manager.py bump minor    # 1.0.0 β†’ 1.1.0

# Create release with tag
python version_manager.py bump minor --tag

See configuration in .version_config.json.


Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

Citation

If you use this code in your research, please cite:

@software{umap_analogy_engine,
  title={UMAP-Inspired Universal Analogy Engine},
  author={Your Name},
  year={2025},
  url={https://github.com/yourusername/ClaudeCodeFrameWork}
}

References

  • UMAP: McInnes, L., Healy, J., & Melville, J. (2018). UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction. arXiv:1802.03426
  • Word Analogies: Mikolov, T., et al. (2013). Linguistic Regularities in Continuous Space Word Representations. NAACL-HLT

License

MIT License (or your preferred license)


Current Version: 1.0.0 Last Updated: 2025-11-18


Support

For questions or issues, please open a GitHub issue or contact [your email].


Current Version: 1.0.0

Last Updated: 2025-11-18

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors