Home Feed Profile


Cognitive Programming Language

Natural Language as Code

LLMs have made it possible to execute natural language specifications directly. This is changing how we approach certain categories of programming tasks.

Last week, we needed to analyze thousands of JSON files from support operations to identify handover patterns between support levels and develop preventive solutions.

The initial implementation used Python scripts for different operations:

A pipeline of scripts handled: fetching conversations, parsing JSON files, checking analysis status, extracting fields, categorizing data, calling LLMs for analysis, managing output directories, saving individual analyses, and generating final summaries. Standard data processing workflow.

So we had per-conversation analysis and a general grand summary of the whole system at the end.

Natural Language Implementation

Based on experience with LLMs that have access to tools (file operations, command execution), I realized these data processing tasks could be expressed directly in natural language.

I rewrote our Python scripts as English specifications. One file simply stated what we needed: check directories for conversations, identify unanalyzed files, process them. The LLM would handle the implementation details through its available tools.

Then in that file, instructing that for each analysis, we want to create a new task, and how to analyze is in a different file. I called it a prompt.

And in that file, I mentioned, in very clear English, what analysis means. That includes reading the JSON file, finding why the handover happened, and for any kind of customer-related information, mask all the sensitive data. Then, what should be the format of output, and then save it.

Similarly, I wrote two more sets of pure English instructions—but again, very clearly. One of them as a driver, again to read the files, and in batches to make sure we do not read too much information at the same time, and one more file about the format for the grand general analysis at the end.

Just imagine—we have these files.

Runtime

Then I gave these to a proper environment. For your information, a proper environment is any kind of tool-using environment that has access to good LLMs. In this case, we have Cline and Roo, many others. Almost any of them will do. They should also have access to our files directly.

Then I ran those pure English prompts, starting from the driver.

And what happened is, they did exactly what the Python script did. And kind of better. Literally the same, or by the way, better output.

I went to the team and said: “Guys, we might not need Python as a programming language for these kinds of tasks anymore. And this is an example.”

The Difference

And there was a huge difference, actually.

The Python script that we had was only readable by a few of us. But now, the other thing that we are using—let’s call it Cognitive Programming Language (CPL)—is readable by almost everyone involved in the project.

They can read it. It’s pure English, plain and clear.

Anyone who can think clearly in instructions and processes, who knows how to solve a problem divided into smaller pieces, who can in an organized way think about solving a problem using tools—which could include any modern human for the last 40,000-50,000 years (the emergence of behaviorally modern humans with our cognitive abilities… oh by the way, they need to speak a language that LLMs understand too)—they will be able to read and enhance this new program right away.

Let Me Show You What I Mean

Here’s what our Python solution looked like (simplified):

def analyze_all_conversations(base_dir):
    conv_dir = Path(base_dir) / "data" / "conversations"
    analysis_dir = Path(base_dir) / "data" / "analysis"
    analysis_dir.mkdir(exist_ok=True)
    
    # Find all conversation files
    conv_files = list(conv_dir.glob("conversation_*.json"))
    
    # Check which are already analyzed
    to_process = []
    for conv_file in conv_files:
        # Extract ID from filename
        conv_id = conv_file.stem.replace("conversation_", "")
        analysis_file = analysis_dir / f"{conv_id}_analysis.md"
        
        # Skip if already analyzed
        if not analysis_file.exists():
            to_process.append((conv_file, conv_id))
    
    print(f"Found {len(conv_files)} conversations")
    print(f"Already analyzed: {len(conv_files) - len(to_process)}")
    print(f"To process: {len(to_process)}")
    
    # Process each unanalyzed conversation
    for conv_file, conv_id in to_process:
        # Load conversation
        with open(conv_file, 'r') as f:
            conv_data = json.load(f)
        
        # Extract and format messages
        messages = conv_data.get("messages", [])
        # ... 100+ more lines of parsing, formatting, calling LLMs, saving...

And here’s the same thing in what I call CPL:

## Driver File: analyze_driver.md

1. List all conversation files in data/conversations/
2. For each conversation:
   - Check if analysis already exists in data/analysis/
   - If already analyzed, skip it
   - If not, create a new task to analyze it following instructions in analyze_task.md
3. Report how many were processed vs. skipped

And like modules in traditional programming, we have another file:

## Task File: analyze_task.md

When given a conversation file:
1. Read the conversation JSON
2. Build timeline showing who spoke and when
3. Identify why the handover happened
4. Classify the reason (tool limitation, knowledge gap, etc.)
5. Suggest improvements to prevent similar handovers
6. Mask all sensitive customer information
7. Save analysis to [conversation_id]_analysis.md
8. Save suggestions to [conversation_id]_suggestions.md

Notice how we organize our CPL program into modules, just like traditional programming? The driver orchestrates, the task file defines the actual analysis logic. This is how we manage scope and complexity in CPL—through clear separation of concerns.

Both produce the same result. The Python needs the Python runtime environment. CPL needs a runtime environment that provides sufficient tooling and LLM access.

The Assembly Programmer’s Objection

Now, wait. I can hear some of you already.

“That’s not real programming! It’s just English that some LLM has to translate into real code!”

Sound familiar?

Just imagine it’s 1965. You’re a seasoned assembly programmer who’s spent years crafting elegant machine code for IBM mainframes. You write instructions like:

LDA #65
STA $0200
JMP $0300

Each line maps directly to CPU operations. This is real programming—you’re speaking the machine’s native tongue.

Then along comes this upstart called FORTRAN. Some young hotshot shows you:

RESULT = A + B * C
PRINT *, 'The answer is:', RESULT

You shake your head dismissively. “That’s not programming! It’s just… English-like nonsense that some compiler has to translate into real code. It won’t even run without the FORTRAN runtime! My assembly runs on bare metal!”

The Pattern Continues

You see the parallel?

Actually, I’m old enough to have seen the same shift before. This is not the first time I’m seeing such a paradigm shift.

There was a time, slightly before me, people used to program in assembly and opcodes at the mainframes, and that was the programming language of those computers. Then came a generation—a new generation of compiled languages on top of those, which added a new higher-level programming language.

I saw the time that dynamic languages came. And at runtime, they were converting our instructions to what computers understand.

So to me, it’s actually kind of a rhyme in the history of computers that now, the language simply changed to cognitive, human, clearly-written instructions in any language. And I see many parallels between the two—the continuation of paradigm change that I want to highlight here.

If you think like an engineer, it’s just history repeating itself. Not revolutionary, not exciting—just the predictable next step in our evolution.

We moved from assembly languages to C. We moved from compiled languages like C to dynamic languages. And now we move from dynamic to cognitive, supported with modern LLMs. Each time, the new language sits one layer above the previous ones, using them as its foundation.

The Hierarchy of Languages

Strip away the aesthetic, and what do you have? A clear hierarchy where each layer sits above the previous:

Assembly: CPU instructions → Direct execution

Python: English-like instructions → Python interpreter → Machine code → Execution

CPL: English instructions → LLM interpreter → Tool calls → Maybe some temp C/Python code (based on LLM decision) → Execution

The differences? The abstraction level and the interpreter complexity. Python’s interpreter is more deterministic and limited. The LLM interpreter is more probabilistic and capable. And crucially—CPL sits at one level higher in the hierarchy, orchestrating all the layers below it.

All programming is specification. When you write Python, you’re specifying what you want the Python interpreter to do. When you write prompts, you’re specifying what you want the LLM to do. The only difference is the interpreter’s sophistication and the fact that it sits at one level higher now.

This higher level matters. Think about Python packages—NumPy, pandas, scikit-learn. They use C underneath for speed, but the problems they solve are nearer to our cognition. They don’t make you think about memory allocation or pointer arithmetic. They let you think about data frames and machine learning models. The lower-level C code is there, doing the heavy lifting, but the Python layer lets you think at a higher level.

CPL does the same thing, just one layer up. It might generate Python or C code when needed, but you’re thinking at the level of business logic and problem-solving, not syntax and implementation details.

Our assembly programmer friend from 1965 would look at Python and say: “You’re not programming, you’re just writing specifications that an interpreter converts to real code!”

He’d be right. And wrong. Because the specification IS the program.

But What About…

“But LLM calls are expensive! And slow!”

Python developers have been handling this objection from C programmers for 30 years. Let me translate their responses:

C Developer (1995): “Python is 100x slower than C!” Python Developer: “And I’m 10x faster at writing it. My time costs $200/hour. CPU time costs $0.001/hour. You do the math. Also, I’ll learn to use C in my packages to speed up everything! I will sit on top of you!”

And now CPL developers will say the same thing. No revolution here—just the usual evolution. Same objections, same responses, one layer higher.

“But how do you debug this?”

Like any other language! You need tooling. CPL depends heavily on communication with LLMs. We can build tools to trace LLM calls, trace what tools those LLM calls requested, trace what we send as a result of those tool calls back to the LLMs. Back and forth, back and forth. The foundation for such tracing tools exists in current LLM platforms. And this is just the beginning.

As soon as we recognize this as a new language, there will be more and more tooling added for making this new language perform better, faster, more cost-optimized, and in a wider range of applications.

Remember: Go, a language created by programming legends at Google, didn’t get comprehensive memory profiling tools for years after its release. Even today, tooling continues to evolve. The tools always follow adoption, not the other way around.

“But prompts need tools to run!”

So? Python needs:

The prompt environment needs:

“But how do you make this reliable?”

This is a general challenge for any LLM-based solution, and based on my experience, it relies heavily on verification layers after each reply.

In a separate post, I mentioned I created a software engineer (it’s a solution at around 400KB prompt): https://blog.zamani.me/story-of-building-llm-developers-glimpsing-the-future. The methods used there—repeated review by LLM and then separate verification and review layers for each solution it provides—will be applicable here too.

Think about how Python handles reliability: unit tests, type checking, linters, code review. CPL will need its own equivalents:

Just like Python evolved from “hope it works” to sophisticated testing frameworks, CPL will evolve its own reliability patterns. The difference is that verification in CPL can be more semantic—checking if the intent was fulfilled, not just if the syntax is correct.

Again, this is a higher-level language and will need its own type of thinking for its problems. The verification isn’t “did this compile?” but “did this achieve what I specified?” And here’s the interesting part: you can write the verification in CPL itself—specifications checking specifications.

The Democratization Effect

This means for any kind of code that our runtime environment supports, we will switch to the new programming language—CPL.

We know this language needs its own environment too. What’s new? Python has the same requirement. By the way, so do other languages, compiled or not. There’s always a runtime requirement.

But here’s the thing—this new language might be the most portable language in existence.

But my point here is, actually, I think we need to recognize this new programming language. LLMs with tool access create the foundation for CPL. But the thing is, the underlying runtime environment is a very interesting problem to work on.

Who Can Program Now?

The Python program that we have—it needs a programmer to change.

The prompt that I wrote—I can distribute it to all our support operations experts, and they can continue working on it with almost zero programming knowledge from my side.

As long as they have a very well-thought, very organized brain. As long as they can understand the problems they are trying to solve. And they can express it in a very clear way to be solved. And as long as a human can follow those instructions using computer tools, they simply can use CPL to do the same thing that current programmers in my team are doing.

That is a shift.

The Business Analyst

Who’s spent years writing precise requirements? They’re no longer writing documents for developers to interpret—they’re writing executable specifications directly.

The Operations Manager

Who deeply understands process optimization? They can now implement solutions immediately, without waiting for sprint planning and developer availability.

The Domain Expert

Who knows exactly how their field works? Their expertise no longer needs to be filtered through someone who’s never worked in their industry.

The Multi-Layer Future

This isn’t a binary future where natural language replaces everything. It’s an additive future where we gain a new, powerful layer:

Cognitive Layer (Natural Language)
    ↓ orchestrates
Application Layer (Python/JavaScript)
    ↓ calls
Systems Layer (Go/Rust/C++)
    ↓ optimizes
Hardware Layer (Assembly/Firmware)
    ↓ controls
Physical Layer (Silicon)

Each layer has its role. The layers never disappear. Assembly didn’t die when FORTRAN arrived. C didn’t vanish when Python emerged. And traditional code won’t disappear with natural language programming.

Why? Because each abstraction layer expands the total programming pie rather than replacing lower levels.

Consider the explosion of embedded systems: Every smartphone, car, IoT device, and smart appliance needs low-level programming. That’s countless programmers writing C, assembly, and hardware-specific code, despite Python being the world’s most popular language.

The same pattern will hold for CPL:

What I Call This: Cognitive Programming Language

I propose Cognitive Programming Language (CPL)—a language that operates at the level of human cognition rather than machine instruction. It’s:

This is fundamentally different from “vibe coding” or other LLM-assisted development approaches. Those methods focus on producing code as the goal. CPL doesn’t treat code generation as the goal at all. The generated code—if any—is just the bytecode equivalent for the cognitive layer. What matters is the specification, the intent, the problem being solved.

Think of it like Java and bytecode: When you write Java, you don’t care about the bytecode it generates—that’s just a necessary execution layer. Similarly, with CPL, any code that gets generated behind the scenes is merely the execution layer, not the focus. The natural language specification IS the program.

Just as we have:

We now add:

Each paradigm coexists, serving different needs in the vast ecosystem of computing.

What’s Next?

What is next, you might ask?

It is for engineers to create better and better runtimes. Expand what is available to those LLMs to run, encapsulate harder problems and package them in a way that those packages become available in turn for that runtime environment to be used.

It is for them to create proper debugging, tracing, annotations for this new language.

But if we do packages, most probably, they will be on a higher level too. For example, a package for a trading platform, a package for the role of being a designer, the role of being a programmer, the role of being a support specialist.

Just imagine—we’re talking about a different level of programming language, and what it can actually do represents the next level too. The next level of complexities that were actually harder to implement in our previous languages.

And just like Python packages solve problems closer to human thinking than C libraries do, CPL packages will solve problems even closer to how we naturally think. Instead of a data analysis package, you might have a “quarterly report generator” package. Instead of a web framework, you might have a “customer portal” package. Each abstraction layer not only sits higher but also thinks more like we do.

This is the natural progression—it happens every time we add a new layer to programming languages.

The Personal Journey

Actually, individual developers naturally evolve through abstraction layers throughout their careers. I started with assembly and C in the early days—the thrill of direct hardware control. Then came Java in the late 90s—object-oriented programming felt revolutionary. The 2000s brought scripting languages—PHP for web development, Perl for text processing and system administration. In the last 8-9 years, I’ve focused on Python for its clarity and Go for its elegant simplicity in systems programming.

Now? I’m developing skills and tooling for this new cognitive layer. I haven’t written assembly in years (though I miss it sometimes), but that foundation shaped how I think about computation. Each language I learned wasn’t a betrayal of the previous one—it was adding another instrument to the orchestra.

Try It Yourself

Want proof? Take any Python function you’ve written. Rewrite it as clear English instructions. Feed it to any modern and sufficiently complex LLM and provide it with all the tools it needs (file reading, writing, execution, search—this is the crucial part many miss!).

This distinction is critical: We’re not talking about chatting with ChatGPT. We’re talking about giving an LLM the same powers you have in your IDE—file system access, code execution, debugging tools. This is what transforms an LLM from a clever autocomplete into a cognitive programming environment.

Watch it execute. Watch it adapt. Watch it improve on your implementation.

Runtime Requirements: The Foundation of CPL

A crucial aspect of CPL that needs to be established from the beginning: Every CPL program needs a runtime environment, just like Python needs the Python interpreter. But unlike traditional languages where the runtime is monolithic, CPL’s runtime is modular—a collection of tools that the program explicitly declares it needs.

Let me show you a complete, working example that demonstrates this principle.

Example: Website Health Monitor

Imagine you need to monitor your company’s websites, check for broken links, validate SSL certificates, and alert on issues. Here’s how you’d write this in CPL:

The Requirements File: monitor_requirements.md

## Runtime Requirements for Website Monitor

This program requires the following tools from the runtime environment:

### Required Tools:
1. **http_request**: Make HTTP/HTTPS requests to URLs
   - Must support: GET, HEAD methods
   - Must return: status codes, headers, response time
   - Must handle: redirects, timeouts

2. **read_file**: Read files from the filesystem
   - Must support: text files, JSON, CSV formats
   - Must provide: line-by-line reading for large files

3. **write_file**: Write results to filesystem
   - Must support: creating directories if needed
   - Must handle: append mode, overwrite mode

4. **execute_command**: Run system commands
   - Must support: curl, openssl (for SSL checks)
   - Must capture: stdout, stderr, exit codes

5. **send_notification**: Send alerts
   - Must support: email OR slack OR console output
   - Fallback: If no notification service, write to alerts.log

6. **schedule_task**: Run tasks periodically
   - Must support: cron-like scheduling OR manual trigger
   - Fallback: Run once if scheduling unavailable

### Environment Check:
Before execution, verify all required tools are available.
If any required tool is missing:
1. List the missing tools
2. Suggest alternatives if available
3. Stop execution and notify the user

### Performance Requirements:
- Memory: Ability to handle up to 1000 URLs in memory
- Concurrency: Preferred but not required (fallback to sequential)
- Timeout handling: Must support 30-second timeouts per request

The Main Program: monitor.md

## Website Health Monitor

### Initialize
1. Read configuration from sites.json containing:
   - List of websites to monitor
   - Check frequency for each site
   - Alert thresholds

2. Verify runtime requirements (see monitor_requirements.md)
   - If requirements not met, stop and report what's missing
   - Log which tools are available and their versions

### Main Monitoring Loop
For each website in the configuration:

1. **Check HTTP Status**
   - Send HEAD request to the URL
   - Record response code and time
   - If response code >= 400, mark as "failed"
   - If response time > threshold, mark as "slow"

2. **Check SSL Certificate** (for HTTPS sites)
   - Execute: openssl s_client -connect {domain}:443 -servername {domain}
   - Parse expiration date from output
   - If expiring within 30 days, mark as "warning"
   - If expired, mark as "critical"

3. **Check for Broken Links** (optional, if deep_check enabled)
   - Fetch the main page content
   - Extract all internal links
   - For each link (up to 50):
     - Send HEAD request
     - Record any 404s or other errors

4. **Generate Report**
   - Create markdown report with:
     - Timestamp of check
     - Status of each site (✅ healthy, ⚠️ warning, ❌ error)
     - Response times chart
     - SSL expiration dates
     - List of any broken links found
   - Save to reports/[date]_health_report.md

5. **Send Alerts** (if issues found)
   - If critical issues (site down, SSL expired):
     - Send immediate notification
     - Include site name, issue type, duration
   - If warnings (slow response, SSL expiring soon):
     - Add to daily digest
     - Send digest at configured time

### Error Handling
- If http_request fails: retry 3 times with exponential backoff
- If all retries fail: mark site as "unknown" and continue
- If notification fails: write to local alert file and continue
- Log all errors to monitor_errors.log with full context

### Schedule
Run every 5 minutes during business hours (9 AM - 6 PM)
Run every 30 minutes during off-hours

The Configuration: sites.json

{
  "sites": [
    {
      "url": "https://example.com",
      "name": "Main Website",
      "response_threshold_ms": 2000,
      "deep_check": true
    },
    {
      "url": "https://api.example.com/health",
      "name": "API Server",
      "response_threshold_ms": 500,
      "deep_check": false
    }
  ],
  "notifications": {
    "email": "[email protected]",
    "slack_webhook": "https://hooks.slack.com/...",
    "daily_digest_time": "09:00"
  }
}

How This Actually Runs

When you execute this CPL program in a compatible environment (like Roo or Cline), here’s what happens:

  1. Requirements Check: The runtime first reads monitor_requirements.md and verifies it has all necessary tools. If http_request is missing, it stops immediately and tells you.

  2. Tool Mapping: The runtime maps English instructions to actual implementations:

    • “Send HEAD request” → http_request tool with method=“HEAD”
    • “Execute openssl” → execute_command tool with command=“openssl…”
    • “Create markdown report” → write_file tool with format=“markdown”
  3. Execution: The LLM interprets each instruction, calling the appropriate tools with correct parameters. It handles the control flow, loops, conditions, and error handling.

  4. State Management: The runtime maintains state between steps—remembering which sites were checked, accumulating report data, tracking retry counts.

Why Runtime Requirements Matter

This isn’t just documentation—it’s an executable contract. Traditional programs crash mysteriously when dependencies are missing. CPL programs tell you exactly what they need upfront.

Compare this to Python:

import requests  # Crashes at runtime if not installed
import ssl       # Part of standard library, but what version?
import smtplib   # For email, but needs configuration

Versus CPL requirements:

Required: http_request tool (with specific capabilities)
Required: notification service (with fallback options)

The CPL approach is more human-readable and more explicit about what the program actually needs to function.

The Evolution of Runtime Environments

As CPL develops, we will need standardized runtimes, each providing different tool sets:

Basic Runtime (file operations + command execution):

Web Runtime (basic + network tools):

Development Runtime (web + code tools):

Enterprise Runtime (everything + integrations):

Each runtime publishes its capabilities, and CPL programs declare which capabilities they need. This creates a marketplace of runtimes and programs, where compatibility is explicit and verifiable.

The Tool Abstraction Layer

Just as Python’s requests library abstracts away the complexities of HTTP, CPL tools abstract away implementation details. The beauty is that the abstraction level matches human thinking:

Both accomplish the same task, but CPL’s version is readable by anyone who understands English, not just programmers.

Another Example: Document Processing Pipeline

Let me show you another real-world example that demonstrates how CPL programs explicitly declare their dependencies. This time, we’ll build a document processing pipeline that converts various formats, extracts metadata, and organizes files.

Requirements Declaration: doc_processor_requirements.md

## Runtime Requirements for Document Processor

### Mandatory Tools:
1. **read_file**: Read documents from filesystem
   - Must support: PDF, DOCX, TXT, MD, JSON
   - Must handle: Large files (up to 100MB)
   - Must provide: Error messages for unsupported formats

2. **write_file**: Save processed documents
   - Must support: Creating nested directories
   - Must handle: Concurrent writes safely
   
3. **extract_text**: Extract text content from documents
   - Must support: PDF text extraction
   - Must support: DOCX text extraction
   - Fallback: Return empty string if extraction fails

4. **search_pattern**: Search for patterns in text
   - Must support: Regular expressions
   - Must return: Match positions and context

5. **move_file**: Organize files into directories
   - Must support: Atomic moves
   - Must handle: Cross-filesystem moves

### Optional Tools (enhance functionality if available):
1. **ocr_scan**: OCR for scanned PDFs
   - If available: Process image-based PDFs
   - If not available: Skip OCR, log as "text extraction only"

2. **translate_text**: Multi-language support
   - If available: Translate non-English documents
   - If not available: Process in original language only

3. **generate_thumbnail**: Create document previews
   - If available: Generate PNG thumbnails
   - If not available: Skip preview generation

### Compatibility Matrix:
If runtime provides:
- All mandatory tools → Full functionality
- Mandatory + ocr_scan → Enhanced PDF processing
- Mandatory + translate_text → Multi-language support
- Mandatory only → Basic processing mode

### Failure Modes:
If any mandatory tool is missing:
1. Print detailed report of missing tools
2. Suggest minimum runtime needed (e.g., "Requires Web Runtime or higher")
3. Exit with clear error message

The Processing Logic: process_documents.md

## Document Processing Pipeline

### Startup Sequence
1. Validate runtime capabilities (see doc_processor_requirements.md)
2. Check for optional tools and set feature flags:
   - has_ocr = check if ocr_scan available
   - has_translation = check if translate_text available
   - has_thumbnails = check if generate_thumbnail available
3. Create processing directories:
   - inbox/ (documents to process)
   - processed/ (completed documents)
   - archived/ (organized by date and type)

### Main Processing Loop
For each document in inbox/:

1. **Identify Document Type**
   - Read first 1KB of file
   - Detect format (PDF, DOCX, TXT, etc.)
   - If unknown format, move to inbox/unsupported/

2. **Extract Content**
   - Use extract_text to get document text
   - If PDF returns empty text (likely scanned image PDF):
     - IF has_ocr is true:
       - Apply ocr_scan to extract text from images
       - Add note to metadata: "OCR applied"
     - IF has_ocr is false:
       - Log: "Scanned PDF detected but OCR not available"
       - Add to metadata: "text_extraction_failed: OCR unavailable"
       - Continue processing with empty text (will be classified as "needs_review")
   - Store extracted text in memory

3. **Extract Metadata**
   Search for these patterns in the text:
   - Date patterns (various formats)
   - Email addresses
   - Phone numbers
   - Invoice/PO numbers
   - Names (using common name patterns)
   - Monetary amounts

4. **Classify Document**
   Based on content patterns, classify as:
   - Invoice (contains invoice number, amounts, due date)
   - Contract (contains party names, signatures, terms)
   - Report (contains sections, conclusions, data)
   - Correspondence (contains greeting, closing, informal tone)
   - Other (doesn't match known patterns)

5. **Language Processing** (if has_translation)
   - Detect document language
   - If not English, translate key sections
   - Add translation to metadata

6. **Generate Preview** (if has_thumbnails)
   - Create 256x256 PNG thumbnail of first page
   - Save as document_name_thumb.png

7. **Organize and Archive**
   Move to: archived/[year]/[month]/[document_type]/
   Create manifest.json with:
   - Original filename
   - Processing date
   - Extracted metadata
   - Classification confidence
   - Applied enhancements (OCR, translation, etc.)

### Batch Report
After processing all documents, generate summary.md:
- Total documents processed
- Breakdown by type
- Documents requiring manual review
- Failed extractions
- Features used (OCR count, translations, etc.)

The Configuration: doc_config.json

{
  "patterns": {
    "invoice": ["invoice#", "amount due", "payment terms"],
    "contract": ["whereas", "party", "agreement", "signature"],
    "report": ["executive summary", "conclusion", "findings"]
  },
  "organization": {
    "archive_path": "./archived",
    "keep_originals": true,
    "date_format": "YYYY/MM"
  },
  "processing": {
    "max_file_size_mb": 100,
    "concurrent_files": 5,
    "retry_failed": true
  }
}

The Beauty of Explicit Requirements

This CPL program demonstrates adaptive behavior based on its environment. When it encounters a scanned PDF (image-only) but OCR isn’t available, it doesn’t crash or stop processing. Instead, it:

  1. Logs that OCR would be helpful but isn’t available
  2. Marks the document as “needs_review” in the metadata
  3. Continues processing other documents
  4. Reports at the end which documents couldn’t be fully processed

This graceful degradation is possible because the program explicitly checks for OCR availability at startup and adapts its behavior accordingly. This is the power of explicit runtime requirements.

In traditional programming, you might write:

try:
    import pytesseract  # For OCR
except ImportError:
    print("Warning: OCR not available")
    OCR_AVAILABLE = False

But this doesn’t tell you:

The CPL approach makes everything explicit and human-readable.

The Runtime Contract: A New Programming Paradigm

This approach represents more than just tool requirements—it’s a fundamental shift in how programs declare their relationship with their environment.

Traditional Approach: Implicit Dependencies

In traditional programming, dependencies are often discovered at runtime:

CPL Approach: Explicit Contracts

CPL programs negotiate with their environment:

This isn’t just error handling—it’s a conversation between the program and its runtime about what’s possible.

The Portability Revolution

Because CPL programs declare their needs explicitly, they become incredibly portable. The same document processor can run on:

The program adapts to what’s available, using advanced features when present, falling back gracefully when not.

Standardization Through Natural Language

We don’t need complex API specifications or version matrices. The requirements are written in plain English:

Any runtime developer can read these requirements and understand exactly what their runtime needs to provide.

The Future: Composable Runtimes

Imagine a future where you can compose runtimes like building blocks:

## My Custom Runtime

Include capabilities from:
- Basic Runtime (file operations)
- Web Runtime (HTTP requests)
- ML Runtime (text analysis, OCR)
- Database Runtime (SQL operations)
- Cloud Runtime (AWS/Azure APIs)

Your CPL programs would automatically discover available tools and adapt their behavior accordingly. A program written today could gain new capabilities tomorrow just by running on an enhanced runtime—without changing a single line of the program itself.

Practical Adoption: Starting Today

You don’t need to wait for the future. You can start writing CPL programs today:

  1. Choose a runtime: Roo, Cline, or any LLM with tool access
  2. Write requirements first: What tools does your logic need?
  3. Write in clear English: Describe what should happen, not how
  4. Test on different runtimes: See how your program adapts

The patterns I’m proposing here can be implemented now with existing tools. The benefits are immediate and tangible. The question isn’t whether CPL will become mainstream—it’s whether you’ll be ready when it does.

Conclusion

Last week, I stopped writing Python for a whole category of tasks. Not because Python failed me, but because something better emerged. Something that lets my entire team—not just the programmers—participate in building solutions.

This is the paradigm shift I see coming. It’s not revolutionary. It’s not even exciting. It’s just the inevitable next step.

And that’s exactly why I know it’s real. The most profound changes in technology are rarely the flashy ones—they’re the obvious-in-hindsight evolutions that feel almost boring in their inevitability.

The assembly programmers were right to be skeptical of FORTRAN. The C programmers were right to question Python. And today’s programmers are right to question CPL.

But being right about the challenges doesn’t stop the evolution. It never has.

This is what’s emerging—Cognitive Programming Language. Where the only syntax you need to master is clear thinking, and the only compiler you need is one that understands intent.

The future isn’t about AI replacing programmers. It’s about everyone becoming one.

Posted on October 23, 2025

← Next post    ·    Previous post →