Cohort builder code API

README.md

@@ -83,64 +83,113 @@ circe process cohort.json --validate --sql --markdown
 
 See the [CLI Documentation](#command-line-interface) section below for more details.
 
-### Python API
+## High-Level Building APIs
+
+CIRCE Python provides two high-level APIs for building cohorts without manually constructing complex JSON/Pydantic models.
+
+### 1. Context Manager API (`circe.cohort_builder`)
+**Best for: LLMs, beginners, and interactive development.**
+This Pythonic API uses `with` blocks and auto-builds on exit.
+
+```python
+from circe.cohort_builder import CohortBuilder
+from circe.vocabulary import concept_set, descendants
+from circe.api import build_cohort_query
+
+# 1. Define concept sets
+t2dm = concept_set(descendants(201826), id=1, name="T2DM")
+metformin = concept_set(descendants(1503297), id=2, name="Metformin")
+
+# 2. Build cohort using context manager
+with CohortBuilder("New Metformin Users with T2DM") as cohort:
+    cohort.with_concept_sets(t2dm, metformin)
+    cohort.with_drug(concept_set_id=2)  # Entry: metformin exposure
+    cohort.first_occurrence()  # First exposure only
+    cohort.with_observation_window(prior_days=365)  # 365 days prior
+    cohort.min_age(18)  # Adults only
+    cohort.require_condition(concept_set_id=1, within_days_before=365)
+
+    with cohort.include_rule("No Prior Insulin") as rule:
+        rule.exclude_drug(3, anytime_before=True)
+
+# 3. Access the built expression and generate SQL
+sql = build_cohort_query(cohort.expression)
+```
+
+### 2. Capr-style API (`circe.capr`)
+**Best for: Power users familiar with the R `Capr` package.**
+A functional, declarative API for programmatic cohort definition.
+
+```python
+from circe.capr import (
+    cohort, entry, condition_occurrence, drug_exposure,
+    at_least, exactly, with_all, during_interval, event_starts
+)
+
+# Build using functional composition
+my_cohort = cohort(
+    title="T2DM on Metformin",
+    entry=entry(
+        drug_exposure(concept_set_id=2, first_occurrence=True),
+        observation_window=(365, 0)
+    ),
+    attrition=attrition(
+        has_t2dm=with_all(
+            at_least(1, condition_occurrence(1), 
+                during_interval(event_starts(before=365)))
+        )
+    )
+).build()
+```
+
+## Advanced Usage: Raw Pydantic Models
+
+For full control, you can use the underlying Pydantic models that replicate the Java CIRCE-BE internal structure.
 
 ```python
 from circe import CohortExpression
 from circe.cohortdefinition import PrimaryCriteria, ConditionOccurrence
 from circe.cohortdefinition.core import ObservationFilter, ResultLimit
 from circe.vocabulary import ConceptSet, ConceptSetExpression, ConceptSetItem, Concept
 
-# Create a cohort expression
+# Create a cohort expression using raw models
 cohort = CohortExpression(
-    title="Type 2 Diabetes Cohort",
+    title="Raw Model Example",
     primary_criteria=PrimaryCriteria(
-        criteria_list=[
-            ConditionOccurrence(
-                codeset_id=1,
-                first=True
-            )
-        ],
+        criteria_list=[ConditionOccurrence(codeset_id=1, first=True)],
         observation_window=ObservationFilter(prior_days=0, post_days=0),
         primary_limit=ResultLimit(type="All")
     ),
-    concept_sets=[
-        ConceptSet(
-            id=1,
-            name="Type 2 Diabetes",
-            expression=ConceptSetExpression(
-                items=[
-                    ConceptSetItem(
-                        concept=Concept(
-                            concept_id=201826,
-                            concept_name="Type 2 diabetes mellitus"
-                        ),
-                        include_descendants=True
-                    )
-                ]
-            )
-        )
-    ]
+    concept_sets=[...]
 )
+```
 
-# Generate SQL using the API
-from circe.api import build_cohort_query
-from circe.cohortdefinition import BuildExpressionQueryOptions
-
-options = BuildExpressionQueryOptions()
-options.cdm_schema = 'cdm'
-options.vocabulary_schema = 'cdm'
-options.cohort_id = 1
-options.target_table = 'scratch.cohort'
-sql = build_cohort_query(cohort, options)
-print(sql)
+## AI Agent Integration
+
+CIRCE Python provides skill documentation for AI agents that need to generate cohort definitions programmatically.
+
+```python
+from circe import get_cohort_builder_skill, list_skills
+
+# List available skills
+print(list_skills())  # ['cohort_builder']
+
+# Get skill documentation for an AI agent
+skill_docs = get_cohort_builder_skill()
+# Returns markdown documentation describing the CohortBuilder API
 ```
 
+The skill documentation includes:
+- Context manager API usage patterns
+- Available entry event methods
+- Inclusion/exclusion criteria syntax
+- Named rule contexts for attrition tracking
+
 ## What's Included
 
 This package provides a complete Python implementation of CIRCE-BE with:
 
-- **3,400+ passing tests** with focused coverage on core logic
+- **800+ passing tests** with focused coverage on core logic
 - **18+ SQL builders** for all OMOP CDM domains:
   - Condition Occurrence/Era
   - Drug Exposure/Era

circe/__init__.py

@@ -32,6 +32,7 @@
     build_cohort_query,
     cohort_print_friendly,
 )
+from .skills import get_cohort_builder_skill, get_skill, list_skills
 
 from circe.cohortdefinition import (
     CohortExpression, Criteria, CorelatedCriteria, DemographicCriteria,
@@ -186,5 +187,10 @@ def get_json_schema() -> dict:
     "cohort_expression_from_json",
     "build_cohort_query",
     "cohort_print_friendly",
-    "safe_model_rebuild"
+    "safe_model_rebuild",
+    # Skills for AI agents
+    "get_cohort_builder_skill",
+    "get_skill",
+    "list_skills",
 ]
+