christofy 1.1.0

Christofy is a lightweight, modular PyTorch-based AI toolkit that unifies essential deep learning capabilities. It supports Image Classification, Segmentation, and advanced Vision Analysis with clean, easy-to-use APIs. With built-in Retrieval-Augmented Generation (RAG) powered by ChromaDB and Ollama, it seamlessly blends vision and language intelligence. Designed for flexibility and speed, Christofy is your all-in-one arsenal for building modern AI solutions.

Christofy 🧠📦✨

Christofy is a comprehensive AI toolkit that combines deep learning, computer vision, and intelligent agent capabilities. Built on PyTorch and integrated with modern LLMs, it provides everything you need for image classification, vision analysis, document understanding, and building intelligent AI agents.

---

🚀 Features

Core Capabilities

• ✅ Image Classification: Train CNN classifiers (ResNet18) for binary and multi-class tasks
• ✅ Vision Analysis: Multimodal AI for image understanding with Ollama integration
• ✅ RAG Pipeline: Retrieval-Augmented Generation for document analysis
• ✅ Image Segmentation: Graph-based segmentation with customizable parameters
• ✅ AutoML: Automated machine learning for tabular data
• ✅ AI Agents: Build intelligent agents with custom tools, memory, and personality (NEW in v1.1.0)

Agent Features (v1.1.0)

• 🤖 Multi-LLM Support: OpenAI, Claude, Gemini, and Groq
• 🔧 Custom Tools: Register any Python function as an agent tool
• 🧠 Memory System: Short-term conversation memory
• 🎭 Personalities: Pre-built templates (teacher, researcher, coder, etc.)
• 🔍 Web Search: Built-in DuckDuckGo integration
• 📚 RAG Integration: Query documents and knowledge bases
• ⚡ Async Support: Run tools asynchronously

Supported File Formats

• Images: JPG, PNG, BMP, and more
• Documents: PDF, DOCX, TXT, JSON
• Data: CSV, Excel (XLSX, XLS)

---

📦 Installation

pip install christofy

Optional Dependencies

For PDF support:

pip install PyPDF2  # or pdfplumber

For DOCX support:

pip install python-docx

For agent web search:

pip install ddgs

For agent LLM support:

pip install openai anthropic google-generativeai groq

For .env file support (recommended):

pip install python-dotenv

---

📚 Usage

🤖 AI Agents (NEW in v1.1.0)

Build intelligent agents with custom tools, memory, and personality in just a few lines!

Basic Agent

from christofy.agents import AgentBuilder

# Create a simple agent
agent = AgentBuilder()
agent.create(
    task="You are a helpful AI assistant",
    llm="openai:gpt-4o",  # or claude:sonnet, gemini:pro, groq:llama3
)

# Ask questions
response = agent.ask("Explain quantum computing in simple terms")
print(response)

Agent with Tools

from christofy.agents import AgentBuilder, tool

# Define custom tools
@tool(name="calculator", description="Evaluate mathematical expressions")
def calculator(expression: str) -> str:
    """Calculate the result of a math expression."""
    try:
        result = eval(expression)
        return f"Result: {result}"
    except Exception as e:
        return f"Error: {e}"

@tool(name="word_count", description="Count words in a text")
def word_count(text: str) -> str:
    """Count the number of words in the given text."""
    count = len(text.split())
    return f"Word count: {count}"

# Create agent with tools and memory
agent = AgentBuilder()
agent.create(
    task="You are a helpful assistant with calculation and text analysis abilities",
    tools=["calculator", "word_count", "websearch"],  # Built-in + custom tools
    llm="openai:gpt-4o",
    memory=True,  # Enable conversation memory
    temperature=0.7
)

# Use the agent
print(agent.ask("What is 125 * 847?"))
print(agent.ask("Count the words in: The quick brown fox jumps"))
print(agent.ask("Search for the latest AI news"))

Agent with Personality

from christofy.agents import AgentBuilder, list_personalities

# See available personalities
print(list_personalities())
# ['default', 'teacher', 'researcher', 'coder', 'assistant', 'analyst', 'creative']

# Create a teacher agent
agent = AgentBuilder()
agent.create(
    task="Help students learn programming",
    personality="teacher",
    llm="claude:sonnet",
    memory=True
)

response = agent.ask("How do loops work in Python?")
print(response)

Agent with RAG (Document Query)

from christofy.agents import AgentBuilder

agent = AgentBuilder()
agent.create(
    task="You are a document analysis assistant",
    tools=["rag"],
    llm="openai:gpt-4o",
)

# Configure RAG with your documents
agent.configure_rag(data_path="./documents")  # folder, file, or raw text

# Query your documents
response = agent.ask("What are the key findings in the research papers?")
print(response)

Supported LLM Providers

# OpenAI
agent.create(llm="openai:gpt-4o")      # GPT-4o
agent.create(llm="openai:gpt-4")       # GPT-4
agent.create(llm="openai:gpt-3.5")     # GPT-3.5 Turbo

# Claude (Anthropic)
agent.create(llm="claude:sonnet")      # Claude Sonnet 4.5
agent.create(llm="claude:opus")        # Claude Opus 4.5
agent.create(llm="claude:haiku")       # Claude Haiku 4.5

# Google Gemini
agent.create(llm="gemini:pro")         # Gemini 1.5 Pro
agent.create(llm="gemini:flash")       # Gemini 1.5 Flash

# Groq
agent.create(llm="groq:llama3")        # Llama 3 70B
agent.create(llm="groq:mixtral")       # Mixtral 8x7B

API Key Configuration

You can provide API keys in three ways:

1. Using a .env file (Recommended)

Create a .env file in your project root:

OPENAI_API_KEY=your-openai-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here
GOOGLE_API_KEY=your-google-key-here
GROQ_API_KEY=your-groq-key-here

Install python-dotenv:

pip install python-dotenv

2. Using environment variables

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"
export GROQ_API_KEY="your-key"

3. Directly in code

agent = AgentBuilder()
agent.create(
    task="You are a helpful assistant",
    llm="openai:gpt-4o",
    api_key="your-api-key-here"  # Pass directly
)

---

---

📸 Image Classification

import christofy

# Train a model
christofy.train_model(
    data_dir="path/to/dataset",
    learning_rate=0.001,
    epochs=10,
    batch_size=32,
    output_dir="output"
)

# Make predictions
predicted_class = christofy.predict_image(
    model_path="output/model.pth",
    image_path="path/to/image.jpg"
)

---

🔍 RAG Pipeline (Retrieval-Augmented Generation)

from christofy import run_rag_pipeline

# Example usage
response = run_rag_pipeline(
    data="path/to/documents",  # Can be file, directory, or text
    query="Your question here?",
    model="llama2",              # Your local Ollama model
    embedding_model="nomic-embed-text",  # For embeddings
    temperature=0.7
)

print(response)

Supported File Formats:

• PDF files (requires PyPDF2 or pdfplumber)
• Word documents (DOCX) (requires python-docx)
• CSV and Excel files (requires pandas)
• Text files (TXT)
• JSON files

---

👁️ Vision Analysis

from christofy import vision_spell

# Basic usage
vision_spell("image.jpg", "What do you see?")

# With model selection
vision_spell("image.jpg", "What do you see?", model="llava:13b")

# Full parameters
vision_spell(
    image_path="image.jpg",
    question="What do you see?",
    model="llava",
    temperature=0.7,
    max_tokens=None,
    system_prompt=None,
    conversation_mode=False
)

# Conversation mode
chat = vision_spell("image.jpg", "What do you see?", conversation_mode=True)
chat.ask("What colors are present?")
chat.ask("Is this indoors or outdoors?")

# Export conversation
chat.export_conversation("json")
chat.export_conversation("txt")

# Batch processing
from christofy import batch_vision_analysis

batch_vision_analysis(
    image_paths=["img1.jpg", "img2.png"],
    questions="What do you see?",
    model="llava"
)

# Utility functions
from christofy import list_vision_models, get_system_info, show_module_info

# Alternative function name
from christofy import vision
vision("image.jpg", "What do you see?")

---

🎨 Image Segmentation

from christofy import segmenter

# Basic usage with default parameters
segmenter("image.jpg")

# With custom parameters
segmenter(
    image_path="image.jpg",
    sigma=0.5,           # Standard deviation for Gaussian smoothing
    merge_threshold=500,  # Threshold for merging segments
    min_size=50          # Minimum segment size
)

---

🤖 Machine Learning for Tabular Data

from christofy.ml import ml_trainer, ml_predictor

# Example 1: AutoML (automatic algorithm selection)
result1 = ml_trainer(
    data="data.csv",  # Replace with your CSV file
    target="target",  # Replace with your target column
    hyperparams={
        "test_size": 0.3,
        "cv": 5
    },
    save_path="automl_model.pkl"
)

# Example 2: User-specified algorithm
result2 = ml_trainer(
    data="data.csv",
    target="target",
    algorithm="random_forest",
    hyperparams={
        "test_size": 0.25,
        "cv": 10,
        "n_estimators": 200,
        "max_depth": 8
    },
    save_path="rf_model.pkl"
)

# Example 3: Make predictions
predictions = ml_predictor(
    model_path="automl_model.pkl",
    values=[[5.1, 3.5, 1.4, 0.2], [6.2, 2.8, 4.8, 1.8]]
)

Supported Algorithms:

• AutoML (automatic algorithm selection)
• Random Forest
• Gradient Boosting
• Support Vector Machines
• Logistic Regression
• K-Nearest Neighbors
• And more!

---

🔧 Requirements

Core Dependencies

• Python 3.9+
• PyTorch
• Pillow (for image processing)
• NumPy

Feature-Specific Dependencies

• RAG & Vision: Ollama (for local LLM inference)
• Segmentation: scikit-image, matplotlib
• ML: scikit-learn, pandas
• Agents: openai, anthropic, google-generativeai, groq (based on LLM provider)
• Agent RAG: chromadb, sentence-transformers, pypdf (for PDF support)
• Web Search: duckduckgo-search
• Document Processing: PyPDF2/pdfplumber (PDF), python-docx (Word), pandas (CSV/Excel)

---

🚀 Quick Start Examples

Complete Agent Example

from christofy.agents import AgentBuilder, tool

# Custom tool
@tool(name="get_weather", description="Get current weather for a city")
def get_weather(city: str) -> str:
    # In real scenario, call weather API
    return f"The weather in {city} is sunny, 72°F"

# Create and configure agent
agent = AgentBuilder()
agent.create(
    task="You are a helpful travel assistant",
    tools=["websearch", "get_weather"],
    personality="assistant",
    llm="openai:gpt-4o",
    memory=True,
    temperature=0.7
)

# Multi-turn conversation
print(agent.ask("What's the weather in Paris?"))
print(agent.ask("What are the top attractions there?"))
print(agent.ask("Based on the weather, what should I pack?"))

Vision + RAG Pipeline

from christofy import vision_spell, run_rag_pipeline

# Analyze an image
vision_response = vision_spell(
    "product_image.jpg",
    "Describe this product in detail",
    model="llava"
)

# Query related documentation
doc_response = run_rag_pipeline(
    data="./product_docs",
    query="What are the specifications of this product?",
    model="llama2"
)

print("Vision Analysis:", vision_response)
print("Documentation:", doc_response)

---

🎯 Use Cases

• Chatbots & Virtual Assistants: Build intelligent conversational agents
• Research Assistants: Agents that search the web and analyze documents
• Code Helpers: Programming assistants with personality and tools
• Image Classification: Train models for custom image recognition tasks
• Document Analysis: RAG for intelligent document querying
• Vision AI: Image understanding and multimodal analysis
• Data Science: AutoML for quick model prototyping

---

📖 API Reference

Agent Methods

agent = AgentBuilder()

# Configure the agent
agent.create(
    task: str,                    # System prompt/task description
    tools: list[str] = [],        # List of tool names
    llm: str = "openai:gpt-4o",  # LLM provider and model
    memory: bool = False,         # Enable conversation memory
    personality: str = "default", # Personality template
    temperature: float = 0.7,     # Response randomness (0-1)
    debug: bool = False          # Enable debug logging
)

# Interact with the agent
response = agent.ask(question: str) -> str

# Configure RAG (if using RAG tool)
agent.configure_rag(data_path: str)  # Path to file, folder, or raw text

# Get conversation history (if memory enabled)
history = agent.get_history() -> list[dict]

# Clear conversation memory
agent.clear_memory()

# Preview agent configuration
agent.preview()

Tool Registration & Execution

from christofy.agents import tool, list_tools, run_tool, run_tool_async

# Register a tool
@tool(name="my_tool", description="What the tool does")
def my_tool(arg1: str, arg2: int) -> str:
    return f"Result: {arg1} {arg2}"

# List all registered tools
tools = list_tools()

# 1. Run a tool manually (synchronously)
# If the tool is async, run_tool will automatically run it using asyncio.run()
result = run_tool("my_tool", arg1="test", arg2=42)

# 2. Run a tool manually (asynchronously)
# If the tool is sync, run_tool_async runs it in a thread pool to avoid blocking the event loop
result_async = await run_tool_async("my_tool", arg1="test", arg2=42)

Under the Hood Tool Execution Mechanics

The run_tool and run_tool_async functions act as a compatibility layer between sync and async contexts:

• Sync Context Integration: When working in a synchronous script, you can execute asynchronous tools safely with run_tool().
• Async Context Integration: When building asynchronous systems (such as API servers or GUI loops), running synchronous tools can block the main execution thread. Calling run_tool_async() delegates sync tools to a thread pool via a background executor to prevent blocking.
• Testing & Debugging: Allows developers to isolate, test, and debug tool logic directly, completely bypassing the agent and saving LLM API costs.

---

🆕 What's New in v1.1.0

• 🤖 AI Agent System: Complete agent framework with tools, memory, and personalities
• 🔧 Custom Tools: Decorator-based tool registration system
• 🧠 Multi-LLM Support: OpenAI, Claude, Gemini, and Groq integration
• 🎭 Personality System: 7 pre-built personality templates
• 🔍 Built-in Web Search: DuckDuckGo integration for agents
• 📚 RAG for Agents: Document querying capabilities
• ⚡ Async Tool Support: Run tools asynchronously

---

💡 Advanced Examples

Async Tools

from christofy.agents import tool
import asyncio
import aiohttp

@tool(name="fetch_url", description="Fetch content from a URL asynchronously")
async def fetch_url(url: str) -> str:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

agent = AgentBuilder()
agent.create(
    task="You are a web content analyzer",
    tools=["fetch_url"],
    llm="openai:gpt-4o"
)

Combining Multiple Features

from christofy import vision_spell, ml_trainer, segmenter
from christofy.agents import AgentBuilder, tool

# Image analysis tool
@tool(name="analyze_image", description="Analyze an image using vision AI")
def analyze_image(image_path: str) -> str:
    return vision_spell(image_path, "Describe this image in detail")

# Segmentation tool
@tool(name="segment_image", description="Segment an image into regions")
def segment_image(image_path: str) -> str:
    result = segmenter(image_path)
    return f"Image segmented into {result['num_segments']} regions"

# Create a vision-powered agent
agent = AgentBuilder()
agent.create(
    task="You are a computer vision assistant",
    tools=["analyze_image", "segment_image", "websearch"],
    llm="claude:sonnet",
    memory=True
)

print(agent.ask("Analyze photo.jpg and tell me what you see"))
print(agent.ask("Now segment it and describe the regions"))

---

🐛 Troubleshooting

Agent Issues

• API Key Errors: Ensure environment variables are set (OPENAI_API_KEY, etc.)
• Tool Not Found: Check tool name spelling and registration
• Memory Issues: Memory is session-based, restart to clear

Vision/RAG Issues

• Ollama Connection: Ensure Ollama is running (ollama serve)
• Model Not Found: Pull the model first (ollama pull llava)

Installation Issues

• Missing Dependencies: Install optional packages as needed
• PyTorch Issues: Visit pytorch.org for platform-specific installation

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📞 Support

• GitHub Issues: https://github.com/aswinchristo/christofy/issues
• Documentation: See this README and inline code documentation

---

⭐ Star History

If you find Christofy useful, please consider giving it a star on GitHub!

---

Made with ❤️ by Aswin Christo