Skip to content

README.md

Latest commit

 

History

History
813 lines (595 loc) · 23.1 KB

README.md

File metadata and controls

813 lines (595 loc) · 23.1 KB

CogSol Framework

Version: 0.2.1 (Alpha)

CogSol is a lightweight, agent-first Python framework for building, managing, and deploying AI assistants. It provides scaffolding, agent abstractions, and file-based migration utilities for CogSol projects without requiring an external database.

Table of Contents

Overview

CogSol is designed to provide a Django-like development experience for building AI agents. It uses a code-first approach where you define your agents, tools, and configurations in Python, then use migrations to sync with a remote CogSol API.

Design Philosophy

  • Code-First: Define agents and tools as Python classes
  • Migration-Based Deployments: Track changes via migrations (similar to Django)
  • No Database Required: Uses JSON files for state tracking
  • API-Synchronized: Push local definitions to remote CogSol APIs

Key Features

Feature Description
Agent Definitions Define AI agents as Python classes with configurable attributes
Tool System Create reusable tools with typed parameters and decorators
Topics & Documents Organize knowledge bases with hierarchical topics and document ingestion
Retrievals Configure semantic search across your document collections
Migrations Track and version agent/tool/topic changes
Remote Sync Push definitions to CogSol Cognitive and Content APIs
Interactive Chat Built-in CLI for testing agents
Import/Export Import existing assistants from the API

Installation

# Option A: Install from source
git clone <repository-url> cogsol-framework
cd cogsol-framework

# Create and activate a virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -e .

# Option B: Install from PyPI
pip install cogsol-framework

Using a local .venv keeps project dependencies isolated and prevents conflicts with global Python packages.

Requirements

  • Python 3.9+

After installation, the cogsol-admin command becomes available globally.

Quick Start

1. Create a New Project

cogsol-admin startproject myproject
cd myproject

This creates:

myproject/
├── manage.py           # Project CLI entry point
├── settings.py         # Project configuration
├── .env.example        # Environment template
├── README.md
├── agents/
│   ├── __init__.py
│   ├── tools.py        # Global tool definitions
│   ├── searches.py     # Retrieval tool definitions
│   └── migrations/
│       └── __init__.py
└── data/
    ├── __init__.py
    ├── formatters.py   # Reference formatters
    ├── ingestion.py    # Ingestion configurations
    ├── retrievals.py   # Retrieval configurations
    └── migrations/
        └── __init__.py

2. Create an Agent

python manage.py startagent SalesAgent

This creates a complete agent package:

agents/salesagent/
├── __init__.py
├── agent.py            # Main agent definition
├── faqs.py             # Frequently asked questions
├── fixed.py            # Fixed responses
├── lessons.py          # Contextual lessons
└── prompts/
    └── salesagent.md   # System prompt

3. Configure Environment

CogSol requires API credentials. Visit https://onboarding.cogsol.ai to obtain them and configure your service API key in the portal before running any commands.

Copy .env.example to .env and fill in the credentials obtained from the portal:

COGSOL_ENV=development
COGSOL_API_KEY=your-api-key  # Obtain from https://onboarding.cogsol.ai
# Optional: Azure AD B2C client credentials for JWT
# If not provided, the Auth will be skipped
COGSOL_AUTH_CLIENT_ID=your-client-id
COGSOL_AUTH_SECRET=your-client-secret

4. Create Migrations

python manage.py makemigrations

5. Apply Migrations

python manage.py migrate

6. Configure Your LLM Provider API Key

To run your agents, configure the API key for your preferred LLM provider. The following providers are supported:

  • OpenAI
  • Google Gemini
  • Anthropic

Add your API key at the CogSol Platform.

7. Chat with Your Agent

python manage.py chat --agent SalesAgent

8. Add Document Topics (Optional)

documentation in the examples below is a sample topic name, use any name that fits your use case.

# Create a topic for documents
python manage.py starttopic documentation

# Create nested topics
python manage.py starttopic tutorials --path documentation

# Create migrations for data
python manage.py makemigrations data
python manage.py migrate data

# Ingest documents into a topic
python manage.py ingest documentation ./data/documentation/*.pdf

# Ingest documents into a nested topic
python manage.py ingest documentation/tutorials ./data/documentation/tutorials/*.pdf

Project Structure

A typical CogSol project has the following structure:

myproject/
├── manage.py                    # CLI entry point
├── settings.py                  # Project settings
├── .env                         # Environment variables
├── agents/                      # Agents application
│   ├── __init__.py
│   ├── tools.py                 # Shared tool definitions
│   ├── searches.py              # Retrieval tool definitions
│   ├── migrations/              # Migration files
│   │   ├── __init__.py
│   │   ├── 0001_initial.py
│   │   ├── .applied.json        # Applied migrations tracker
│   │   └── .state.json          # Current state and remote IDs
│   └── <agent-slug>/            # Per-agent package
│       ├── __init__.py
│       ├── agent.py             # Agent class definition
│       ├── faqs.py              # FAQ definitions
│       ├── fixed.py             # Fixed response definitions
│       ├── lessons.py           # Lesson definitions
│       └── prompts/
│           └── <slug>.md        # System prompt
└── data/                        # Data application
    ├── __init__.py
    ├── formatters.py            # Reference formatter definitions
    ├── ingestion.py             # Ingestion configuration definitions
    ├── retrievals.py            # Retrieval configuration definitions
    ├── migrations/              # Migration files
    │   ├── __init__.py
    │   ├── 0001_initial.py
    │   ├── .applied.json
    │   └── .state.json
    └── <topic-path>/            # Topic folder (can be nested)
        ├── __init__.py          # Topic class definition
        └── metadata.py          # Metadata configurations

CLI Commands

CogSol provides the following management commands:

startproject

Create a new CogSol project.

cogsol-admin startproject <project-name> [directory]

Arguments:

  • project-name: Name of the project
  • directory: (Optional) Target directory

Scaffold from Cookbook

You can bootstrap a project from a template or example published in the CogSol Cookbook repository:

# List available templates and examples
cogsol-admin startproject --list-templates
cogsol-admin startproject --list-examples

# Create a project from a cookbook template
cogsol-admin startproject my-agent --from-template subagents

# Create a project from a cookbook example
cogsol-admin startproject my-demo --from-example hello-world

Options:

Flag Description
--from-template NAME Scaffold from templates/<NAME> in the cookbook
--from-example NAME Scaffold from examples/<NAME> in the cookbook
--list-templates List available cookbook templates
--list-examples List available cookbook examples
--force Overwrite existing files when the target directory is not empty
--ref REF Pin the cookbook to a specific branch, tag, or commit SHA (default: main)
--cookbook-repo OWNER/REPO Use a custom cookbook repository (default: cogsol/cogsol-cookbook)
--github-token TOKEN GitHub token for private cookbook repositories

The --ref flag is useful for reproducibility — for example, to ensure all team members scaffold from the same cookbook version:

cogsol-admin startproject my-agent --from-template subagents --ref v1.0.0

Custom Cookbook Repository

By default, the CLI fetches from cogsol/cogsol-cookbook. To use your own repository, pass --cookbook-repo OWNER/REPO directly to startproject. If the repository is private, also pass --github-token.

# Public custom cookbook
cogsol-admin startproject --list-templates --cookbook-repo my-org/my-cookbook
cogsol-admin startproject my-agent --from-template subagents --cookbook-repo my-org/my-cookbook

# Private custom cookbook
cogsol-admin startproject my-agent \
    --from-template internal-agent \
    --cookbook-repo my-org/private-cookbook \
    --github-token $GITHUB_TOKEN

The repository must follow the same directory convention: templates under templates/ and examples under examples/. The CLI output always shows which repository is being used so you can verify the active configuration.

startagent

Create a new agent package with all required files.

python manage.py startagent <agent-name> [app]

Arguments:

  • agent-name: Agent class name (e.g., SalesAgent)
  • app: (Optional) App name, defaults to agents

makemigrations

Generate migration files based on agent/tool/topic changes.

python manage.py makemigrations [app] [--name <suffix>]

Arguments:

  • app: (Optional) App to migrate, agents or data (when omitted, runs both)
  • --name: (Optional) Custom migration name suffix

migrate

Apply pending migrations and sync with the CogSol API.

python manage.py migrate [app]

Arguments:

  • app: (Optional) App to migrate, agents or data (when omitted, runs both)

starttopic

Create a new topic folder under data/.

python manage.py starttopic <topic-name> [--path <parent-path>]

Arguments:

  • topic-name: Name of the topic (used as folder name)
  • --path: (Optional) Parent path for nested topics (e.g., parent/child)

Examples:

# Create a root topic
python manage.py starttopic documentation

# Create a nested topic
python manage.py starttopic tutorials --path documentation
# Creates: data/documentation/tutorials/

ingest

Ingest documents into a topic.

python manage.py ingest <topic> <files...> [options]

Arguments:

  • topic: Topic path (e.g., documentation or parent/child/topic)
  • files: Files, directories, or glob patterns to ingest

Use slash-separated paths for nested topics. For example, if you created tutorials under documentation with starttopic tutorials --path documentation, ingest into it with documentation/tutorials.

For a topic-aligned workflow, place files under data/<topic-path>/ and ingest from that folder (for example, ./data/documentation/*.pdf or ./data/documentation/tutorials/*.pdf).

Options:

  • --doc-type: Document type (defaults to Text Document)
  • --ingestion-config: Name of an ingestion config from data/ingestion.py
  • --pdf-mode: PDF parsing mode (manual, OpenAI, both, ocr, ocr_openai)
  • --chunking: Chunking mode (langchain, ingestor)
  • --max-size-block: Maximum characters per block (default: 1500)
  • --chunk-overlap: Overlap between blocks (default: 0)
  • --separators: Comma-separated chunk separators
  • --ocr: Enable OCR parsing
  • --additional-prompt-instructions: Extra parsing instructions
  • --assign-paths-as-metadata: Assign file paths as metadata
  • --dry-run: Show what would be ingested without uploading

Examples:

# Ingest PDF files
python manage.py ingest documentation ./data/documentation/*.pdf

# Ingest into a child topic
python manage.py ingest documentation/tutorials ./data/documentation/tutorials/*.pdf

# Ingest with custom config
python manage.py ingest documentation ./data/documentation/ --ingestion-config HighQuality

# Dry run to preview
python manage.py ingest documentation ./data/documentation/ --dry-run

topics

List topics from the API or local definitions.

python manage.py topics [options]

Options:

  • --local: Show topics from local definitions instead of API
  • --sync-status: Show synchronization status (local vs API)

importagent

Import an existing assistant from the CogSol API.

python manage.py importagent <assistant-id> [app]

Arguments:

  • assistant-id: Remote assistant ID to import
  • app: (Optional) App name, defaults to agents

chat

Start an interactive chat session with an agent.

python manage.py chat --agent <agent-name-or-id> [app]

Arguments:

  • --agent: Agent name or remote ID (required)
  • app: (Optional) App name, defaults to agents

Chat Commands:

  • /exit or Ctrl+C: Exit the chat
  • /new: Start a new chat session

Core Concepts

Agents

Agents are the central concept in CogSol. An agent is defined as a Python class that inherits from BaseAgent:

from cogsol.agents import BaseAgent, genconfigs
from cogsol.prompts import Prompts

class CustomerSupportAgent(BaseAgent):
    # Core configuration
    system_prompt = Prompts.load("support.md")
    generation_config = genconfigs.QA()

    # Tools
    tools = [MyTool()]
    pretools = []

    # Limits
    max_interactions = 10
    max_msg_length = 2048
    max_consecutive_tool_calls = 5
    temperature = 0.3

    # Behaviors
    initial_message = "Hello! How can I help you today?"
    forced_termination_message = "Thank you for chatting!"
    no_information_message = "I don't have information on that topic."

    # Features
    streaming = False
    realtime = False

    class Meta:
        name = "CustomerSupportAgent"
        chat_name = "Customer Support"
        logo_url = "https://example.com/logo.png"
        primary_color = "#007bff"

Agent Attributes

Attribute Type Description
system_prompt Prompt The system prompt loaded from a file
generation_config genconfigs.* LLM generation configuration
pregeneration_config genconfigs.* Pre-tool generation configuration
tools list[BaseTool] Tools available to the agent
pretools list[BaseTool] Pre-processing tools
temperature float LLM temperature (0.0 - 1.0)
max_interactions int Maximum conversation turns
user_message_length int Maximum user message length
consecutive_tool_calls_limit int Max consecutive tool calls
streaming bool Enable response streaming
realtime bool Enable real-time mode

Tools

Tools extend agent capabilities. The language model decides when to execute them and fills in the parameter values based on the prompt and conversation context.

There are three types of tools on the platform: Scripts, MCP, and Searches.

Define Script Tools in agents/tools.py:

from cogsol.tools import BaseTool, tool_params

class DateTool(BaseTool):
    """Tool that returns the current date in a desired format."""

    name = "get_date"
    description = "Return the current date in desired format or YYYY-MM-DD"
    show_tool_message = False

    @tool_params(
        format={
            "description": "Format to retrieve the date",
            "type": "string",
            "required": False,
        }
    )
    def run(self, format="", chat=None, data=None, secrets=None, log=None):
        from datetime import datetime
        return datetime.utcnow().strftime(format or "%Y-%m-%d")

Rules

  • The tool's main logic must be implemented in the run() method.
  • Helper methods can be defined within the class, but code cannot be shared across class boundaries.
  • All imports must be placed inside the method that uses them — at the run() scope or inside the relevant helper method.
  • The return keyword is reserved and is automatically translated to response =. This means return does not terminate execution early. You can inspect the translated code directly in the Platform if needed.

For best practices and a full overview of tool capabilities, see Script Tools in CogSol Docs.

Retrieval tools connect agents to Content API retrievals. Define them in agents/searches.py:

from cogsol.tools import BaseRetrievalTool
from data.retrievals import ProductDocsRetrieval

class ProductDocsSearch(BaseRetrievalTool):
    name = "product_docs_search"
    description = "Search the product documentation."
    retrieval = ProductDocsRetrieval()
    parameters = [
        {"name": "question", "description": "Search query", "type": "string", "required": True}
    ]

Tool Parameters

The @tool_params decorator defines parameter metadata:

@tool_params(
    param_name={
        "description": "Parameter description",
        "type": "string",      # string, integer, boolean, etc.
        "required": True       # Required or optional
    }
)

FAQs, Fixed Responses, and Lessons

These provide additional context to agents:

FAQs (faqs.py)

from cogsol.tools import BaseFAQ

class PricingFAQ(BaseFAQ):
    question = "What are your pricing plans?"
    answer = "We offer three tiers: Basic ($10/mo), Pro ($25/mo), Enterprise (custom)."

Fixed Responses (fixed.py)

from cogsol.tools import BaseFixedResponse

class ClosingFixed(BaseFixedResponse):
    key = "goodbye"
    response = "Thank you for contacting us. Have a great day!"

Lessons (lessons.py)

from cogsol.tools import BaseLesson

class ToneLesson(BaseLesson):
    name = "Communication Tone"
    content = "Always maintain a professional yet friendly tone."
    context_of_application = "general"

Prompts

Prompts are loaded from markdown files:

from cogsol.prompts import Prompts

# In agent definition
system_prompt = Prompts.load("agent.md")

The prompt file is resolved relative to the agent's prompts/ directory.

Generation Configurations

from cogsol.agents import genconfigs

# Question-Answering mode
generation_config = genconfigs.QA()

# Fast retrieval mode
generation_config = genconfigs.FastRetrieval()

Data & Topics

CogSol provides a complete system for managing document collections and semantic search through the Content API.

Topics

Topics are hierarchical containers for organizing documents. Define them in data/<topic>/:

# data/documentation/__init__.py
from cogsol.content import BaseTopic

class DocumentationTopic(BaseTopic):
    name = "documentation"

    class Meta:
        description = "Product documentation and guides."

Topics can be nested by creating subdirectories:

data/
├── documentation/
│   ├── __init__.py
│   ├── metadata.py
│   └── tutorials/
│       ├── __init__.py
│       └── metadata.py

Metadata Configurations

Define custom metadata fields for documents within a topic:

# data/documentation/metadata.py
from cogsol.content import BaseMetadataConfig, MetadataType

class CategoryMetadata(BaseMetadataConfig):
    name = "category"
    type = MetadataType.STRING
    possible_values = ["Guide", "Tutorial", "Reference", "FAQ"]
    filtrable = True
    required = False

class VersionMetadata(BaseMetadataConfig):
    name = "version"
    type = MetadataType.STRING
    required = True
    default_value = "1.0"

Ingestion Configurations

Define reusable ingestion settings in data/ingestion.py:

from cogsol.content import BaseIngestionConfig, PDFParsingMode, ChunkingMode

class HighQualityConfig(BaseIngestionConfig):
    name = "high_quality"
    pdf_parsing_mode = PDFParsingMode.OCR
    chunking_mode = ChunkingMode.AGENTIC_SPLITTER
    max_size_block = 2000
    chunk_overlap = 100

class FastConfig(BaseIngestionConfig):
    name = "fast"
    pdf_parsing_mode = PDFParsingMode.MANUAL
    chunking_mode = ChunkingMode.LANGCHAIN
    max_size_block = 1500

Use with the ingest command:

python manage.py ingest documentation ./data/documentation/ --ingestion-config high_quality

Reference Formatters

Define how document blocks are formatted when referenced:

# data/formatters.py
from cogsol.content import BaseReferenceFormatter

class DetailedFormatter(BaseReferenceFormatter):
    name = "detailed"
    description = "Include page and category."
    expression = "[{name}, p.{page_num}] ({metadata.category})"

class SimpleFormatter(BaseReferenceFormatter):
    name = "simple"
    expression = "{name}"

Retrievals

Configure semantic search across topics:

# data/retrievals.py
from cogsol.content import BaseRetrieval, ReorderingStrategy
from data.formatters import DetailedFormatter
from data.documentation.metadata import VersionMetadata

class DocumentationRetrieval(BaseRetrieval):
    name = "documentation_search"
    topic = "documentation"
    num_refs = 10
    reordering = False
    strategy_reordering = ReorderingStrategy.NONE
    formatters = {"Text Document": DetailedFormatter}
    filters = []

class FilteredRetrieval(BaseRetrieval):
    name = "v2_docs"
    topic = "documentation"
    num_refs = 5
    filters = [VersionMetadata]

Configuration

Environment Variables

Credentials are obtained from the CogSol onboarding portal at https://onboarding.cogsol.ai. Configure your service API key there before running migrations or using the CLI.

Variable Required Description
COGSOL_API_KEY Yes Service API key — obtain from the portal at https://onboarding.cogsol.ai
COGSOL_ENV No Environment name (e.g., local, development, production)
COGSOL_AUTH_CLIENT_ID No Client Id provided for administrators
COGSOL_AUTH_SECRET No Auth secret provided for administrators

Project Settings (settings.py)

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent
PROJECT_NAME = "myproject"
AGENTS_APP = "agents"

API Reference

For detailed API documentation, see:

License

Copyright © Cognitive Solutions

Alpha release: APIs and features may change between versions.