Welcome to cognition 🧠 a fair-source agent framework in Python developed by Polycog, Inc.. The framework implements a neurosymbolic foundation for complex decision-making, natural language processing, structural knowledge representation, and logical & deterministic reasoning. It enables developers to build trustworthy cognitive agents - agents that are reliable (repeatable, provably correct reasoning), steerable (programmatic enforcement of behavior directives), and explainable (causal provenance of all decisions).

📖 Table of Contents

• Core Concepts
• Library Structure
• Getting Started
• Documentation & Resources

Core concepts

Agent Runtime Loop with Cogent

• What it does: Manages the intelligent agent loop, bridging internal cognitive processes with external environmental sensors and actuators. details
• Agentic AI Equivalent: Harness
• Why use it: Separates core cognitive reasoning from raw API calls. This creates a clean boundary for safety checks, API mocking, and simulation testing.

Knowledge-Augmented DecisionProcess

• What it does: Design agent behavior via a declarative, state-driven execution machine that matches the current environment state against explicit policy directives. details
• Agentic AI Equivalent: Orchestrator; DAG workflows or skills.md
• Why use it: Replaces non-deterministic LLM loops and brittle if-else scripts with declarative state control — enforcing safety guardrails, business logic, and policies at every step.

Structured Knowledge Representation with WorldGraph

• What it does: Declares domain knowledge using strongly-typed, validated data models that can be inspected, queried, and mutated at runtime. details
• Agentic AI Equivalent: engineered or raw prompt context
• Why use it: Gives agents a typed, queryable source of truth instead of relying on fragile context windows or unvalidated text blobs.

4. Language Processing with Data Models

• What it does: Uses LLMs for specific, constrained tasks—such as intent classification (EnumClassifier), generating natural language from facts (describe_facts), and extracting structured data (ModelPopulator) with automated context engineering. details
• Agentic AI Equivalent: Structured Outputs
• Why use it: Restricts LLM operations to strict input/output contracts, keeping non-deterministic text generation out of core control flow.

5. Verifiable Logical Reasoning with SearchPlanner

• What it does: Solves planning sub-problems algorithmically to find an optimal sequence of actions to reach a specified target state. details
• Agentic AI Equivalent: Chain-of-Thought
• Why use it: Guarantees causal validity, completeness, and efficiency for complex multi-step problems without relying on probabilistic LLM guessing.

Note: This project is under active development. Expect regular updates and new features!

🏗️ Library Structure

The library is organized into specialized subpackages to handle distinct cognitive tasks:

cognition.cogent

Core modeling for your (cog)nitive ag(ent) and its surroundings.

• cogent: Defines the fundamental agent loop and behaviors.
• env: Tools for creating and interacting with environmental sensors & actuators.

cognition.decision

Frameworks for managing states and decision-making processes over time.

• chain: Mechanisms for linking sequences of decisions.
• core: Core functionality for decision-making.
• dp: Functionality for knowledge-augmented decision processes.
• stage: Mechanisms for decision processes based upon singular enumerated field.
• state: Re-usable state augmentations.

cognition.knowledge

Handle structured data and complex ontologies.

• organization: Modules for structuring and linking concepts.
• representation: Primitives for representing facts, schemas, and semantic relationships.

cognition.language

Tools for interpreting and generating natural language.

• classification: Text categorization and intent recognition.
• description: Capabilities for generating human-readable descriptions of states or actions.
• population: Tools for extracting data from text to populate knowledge representations.

cognition.reasoning

Engines for logical deduction and automated planning.

• planning: Includes SearchPlanner and various state exploration strategies (DFS, BFS, UCS, A*) using classes like FrontierManager, PriorityQueue, and SearchState. Allows you to define Static and Dynamic transition options to navigate state spaces.

cognition.util

Helpful utilities to streamline your code, including...

• enumeration: self-documenting and executing data.
• functypes: convenience function type descriptors.
• misc: utility code.

🚀 Getting Started

pip install polycog-cognition

Suggested exploration plan:

1. Tutorials: thematic step-by-step guides, interactive Jupyter Notebooks, and complete Python reference implementations.
2. Examples: fully coded mini-applications.
3. Cookbook: annotated recipes related to library features.

📚 Documentation & Resources

For detailed technical descriptions & deep dives into the design philosophy:

• Documentation Home
• Key API Ideas
• Comprehensive API Reference

© 2026 - Polycog, Inc.