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
• Key Features
• Installation
• Quick Start
• Project Structure
• CLI Commands
• Core Concepts
  • Agents
  • Data & Topics
• Configuration
• API Reference
• Contributing

---

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

From Source

git clone <repository-url> cogsol-framework
cd cogsol-framework
pip install -e .

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

To use CogSol you need API credentials. Visit https://onboarding.cogsol.ai to obtain your credentials. Make sure to also configure the service API key in the implantation 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 API key of your preferred LLM provider

To run your agents, you’ll need to configure first the API key of your preferred LLM provider:

• OpenAI
• Google Gemini
• Anthropic

You can add your API key at Cogsol platform

7. Chat with Your Agent

python manage.py chat --agent SalesAgent

8. Add Document Topics (Optional)

documentation in the examples below is only a sample topic name. You can use any topic 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

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:

# `documentation` is just an example topic name.
# 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. Define tools in agents/tools.py:

from cogsol.tools import BaseTool, tool_params

# class SearchTool(BaseTool):
#     description = "Search for information in the knowledge base."
#     
#     @tool_params(
#         query={"description": "Search query", "type": "string", "required": True},
#         limit={"description": "Max results", "type": "integer", "required": False},
#     )
#     def run(self, chat=None, data=None, secrets=None, log=None, 
#             query: str = "", limit: int = 10):
#         """
#         query: The search query.
#         limit: Maximum number of results.
#         """
#         # Implementation here
#         results = perform_search(query, limit)
#         response = format_results(results)
#         return response

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:

• Architecture Documentation
• CLI Commands Reference
• API Client Reference
• Agents & Tools Reference

---

License

Copyright © Cognitive Solutions

---

This is an alpha release. APIs and features may change.