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:
- Python runtime (300MB+)
- Package managers (pip/conda)
- Virtual environments
- Operating system APIs
- C libraries for performance-critical code
The prompt environment needs:
- LLM endpoint
- Basic tools (read_file, write_file, execute_command, new_task)
- Other layers will come too, do not worry!
“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:
- Verification prompts that check the output matches the specification
- Review layers that validate each step before proceeding
- Rollback mechanisms when verification fails
- Test specifications written in natural language
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:
- Performance-critical paths: Still need C/Rust
- Operating systems & databases: Still need systems languages
- Compiler & interpreter development: Someone has to build the Python/JavaScript runtimes
- Tool implementations: The
read_fileandwrite_fileoperations LLMs use? Someone codes those traditionally
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:
- Cognitive because it understands intent, context, and meaning
- Programming because it creates executable specifications
- Language because it has patterns, best practices, and idioms
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:
- Machine languages (assembly)
- Procedural languages (C, Pascal)
- Object-oriented languages (Java, C++)
- Functional languages (Haskell, Lisp)
- Scripting languages (Python, Ruby)
We now add:
- Cognitive languages (Natural language via LLMs)
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:
-
Requirements Check: The runtime first reads
monitor_requirements.mdand verifies it has all necessary tools. Ifhttp_requestis missing, it stops immediately and tells you. -
Tool Mapping: The runtime maps English instructions to actual implementations:
- “Send HEAD request” →
http_requesttool with method=“HEAD” - “Execute openssl” →
execute_commandtool with command=“openssl…” - “Create markdown report” →
write_filetool with format=“markdown”
- “Send HEAD request” →
-
Execution: The LLM interprets each instruction, calling the appropriate tools with correct parameters. It handles the control flow, loops, conditions, and error handling.
-
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):
- read_file, write_file, list_files
- execute_command
- Perfect for: data processing, file management
Web Runtime (basic + network tools):
- http_request, websocket_connect
- parse_html, extract_links
- Perfect for: web scraping, API integration
Development Runtime (web + code tools):
- git_operations, code_analysis
- test_runner, dependency_checker
- Perfect for: CI/CD, code quality checks
Enterprise Runtime (everything + integrations):
- database_query, message_queue
- cloud_service_apis
- Perfect for: business automation
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:
- Python:
response = requests.get(url, timeout=30) - CPL: “Send a GET request to the URL with a 30-second timeout”
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:
- Logs that OCR would be helpful but isn’t available
- Marks the document as “needs_review” in the metadata
- Continues processing other documents
- 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:
- What OCR capabilities are actually needed
- What happens when OCR isn’t available
- What alternative runtimes might provide OCR
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:
- Missing library? Crash.
- Wrong version? Undefined behavior.
- Missing system tool? Silent failure.
CPL Approach: Explicit Contracts
CPL programs negotiate with their environment:
- “I need these tools with these capabilities”
- “If you don’t have X, I can work around it”
- “If you don’t have Y, I cannot run at all”
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:
- A minimal runtime (just the mandatory tools)
- An enterprise runtime (with OCR, translation, and more)
- A future runtime (with tools we haven’t invented yet)
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:
- “Must support PDF text extraction”
- “Should handle files up to 100MB”
- “Optional: OCR for scanned documents”
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:
- Choose a runtime: Roo, Cline, or any LLM with tool access
- Write requirements first: What tools does your logic need?
- Write in clear English: Describe what should happen, not how
- 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